diff --git a/docs/advanced-usage/available-tools/apply-diff.md b/docs/advanced-usage/available-tools/apply-diff.md index 640e2d26..3db20aa1 100644 --- a/docs/advanced-usage/available-tools/apply-diff.md +++ b/docs/advanced-usage/available-tools/apply-diff.md @@ -118,69 +118,3 @@ Example format for the `` block: ``` --- - -## Experimental: Multi-File Edits (`MULTI_FILE_APPLY_DIFF`) - -An experimental version of `apply_diff` allows for applying changes to multiple files within a single tool call. This feature is activated by the `MULTI_FILE_APPLY_DIFF` experiment flag. - -### Key Features of Experimental Mode - -- **Multi-File Operations**: Edit multiple files in one request, streamlining complex refactoring tasks. -- **Batch Approval UI**: When multiple files are targeted, a single UI appears for the user to approve or deny all changes at once, or manage permissions for each file individually. -- **New XML Format**: Introduces a new, more structured XML format using `` and `` tags to handle multiple operations. -- **Backward Compatibility**: The experimental tool remains compatible with the legacy single-file `path` and `diff` parameter format. - -### How It Works (Experimental) - -1. **Experiment Check**: The tool first checks if the `MULTI_FILE_APPLY_DIFF` experiment is enabled. If not, it falls back to the legacy `apply_diff` implementation. -2. **Parameter Parsing**: It parses the new `` XML format to identify all target files and their corresponding diff operations. It can also handle the legacy `path`/`diff` parameters. -3. **Validation and Approval**: - * It validates that all target files exist and are accessible (not blocked by `.rooignore`). - * If multiple files are being modified, it presents a **batch approval** dialog to the user. -4. **Diff Application**: For each approved file, it applies the specified diffs using the `MultiFileSearchReplaceDiffStrategy`. This strategy can apply multiple, non-overlapping changes to a single file. -5. **Results**: It returns a consolidated result message summarizing the outcome for all attempted operations. - -### New Diff Format (Experimental) - -The experimental mode uses a new XML structure within the `` tool call. - -- **``**: A container for all file operations. -- **``**: A block for each file to be modified. Contains `` and one or more `` tags. -- **``**: The relative path to the file. -- **``**: A block containing the change. - - **``**: The `SEARCH/REPLACE` block. - - **``**: (Optional) A line number hint. - -**Example: Modifying two files in one call** - -```xml - - - - src/services/auth.service.ts - - -<<<<<<< SEARCH -:start_line:50 -------- - const token_expiration = '15m'; ->>>>>>> REPLACE - - - - - src/config/auth.config.ts - - -<<<<<<< SEARCH -:start_line:12 -------- - rateLimit: 5, -======= - rateLimit: 10, ->>>>>>> REPLACE - - - - - diff --git a/docs/advanced-usage/available-tools/edit-file.md b/docs/advanced-usage/available-tools/edit-file.md index c5415c11..8cad6822 100644 --- a/docs/advanced-usage/available-tools/edit-file.md +++ b/docs/advanced-usage/available-tools/edit-file.md @@ -1,5 +1,5 @@ --- -description: Replace all occurrences of text in files using the edit_file search-and-replace tool in Roo Code. +description: Replace a uniquely-identified occurrence of text in files using the edit_file search-and-replace tool in Roo Code. keywords: - edit_file - search and replace @@ -11,7 +11,7 @@ keywords: # edit_file -The `edit_file` tool performs search-and-replace operations on files, replacing **all occurrences** of specified text. It provides a straightforward way to make consistent changes across a file when you need to update every instance of a pattern. +The `edit_file` tool performs targeted search-and-replace operations on files. By default it replaces **exactly one** uniquely-identified occurrence and errors if multiple matches are found. It also supports a special file-creation mode when `old_string` is empty. --- @@ -20,35 +20,38 @@ The `edit_file` tool performs search-and-replace operations on files, replacing The tool accepts these parameters: - `file_path` (required): The path of the file to modify relative to the current working directory. -- `old_string` (required): The exact text to search for and replace. -- `new_string` (required): The text to replace all occurrences with. -- `expected_replacements` (optional): Expected number of replacements. If specified, the operation fails if the actual count doesn't match. +- `old_string` (required): The exact text to search for and replace. Pass an empty string (`""`) to create a new file or append to an existing file. +- `new_string` (required): The replacement text. +- `expected_replacements` (optional): Expected number of replacements (defaults to 1). The operation fails if the actual count doesn't match. Use this only when intentionally replacing more than one occurrence. --- ## What It Does -This tool searches for an exact string in a file and replaces **all occurrences** with new text. The replacement is performed globally across the entire file, making it ideal for consistent updates like renaming variables, updating API endpoints, or fixing repeated patterns. +This tool searches for an exact string in a file and replaces **exactly one** occurrence with new text. The search string must uniquely identify the target location. If multiple matches are found, the tool returns an error unless `expected_replacements` is explicitly set to match. When `old_string` is empty, the tool creates a new file or appends `new_string` to an existing file. --- ## When is it used? -- When renaming variables, functions, or identifiers throughout a file -- When updating repeated string literals or configuration values -- When fixing consistent typos or outdated terminology -- When replacing all instances of a deprecated API or import path +- When making a targeted change to a specific, uniquely identifiable location in a file +- When updating a specific string literal or configuration value at a known location +- When fixing a specific instance of a typo or outdated terminology +- When replacing a uniquely-identified occurrence of a deprecated API or import path +- When creating a new file or appending content to an existing file (`old_string=""`) - When you need to ensure exact match replacement without fuzzy logic --- ## Key Features -- Replaces **all occurrences** by default (global replacement) +- Replaces **exactly one** uniquely-identified occurrence by default +- Errors if multiple matches are found (unless `expected_replacements` is explicitly set) +- `old_string=""` mode: creates a new file or appends content to an existing file - Exact string matching (no regex or fuzzy matching) -- Optional validation via `expected_replacements` parameter +- Optional `expected_replacements` for intentional multi-occurrence replacements - Shows preview of changes before applying -- Fails safely if expected replacement count doesn't match actual +- Fails safely if actual replacement count doesn't match `expected_replacements` - Preserves file formatting and structure --- @@ -56,7 +59,7 @@ This tool searches for an exact string in a file and replaces **all occurrences* ## Limitations - Requires exact string matches (case-sensitive, whitespace-sensitive) -- Always replaces all occurrences (cannot target specific instances) +- Errors if the search string matches more than one location (unless `expected_replacements` is set) - Cannot use regular expressions or patterns - Not suitable for context-dependent replacements - Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits @@ -68,10 +71,10 @@ This tool searches for an exact string in a file and replaces **all occurrences* When the `edit_file` tool is invoked, it follows this process: 1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters. -2. **File Loading**: Reads the target file content. -3. **Search Operation**: Searches for all occurrences of `old_string` in the file. -4. **Count Validation**: If `expected_replacements` is specified, validates the actual occurrence count matches. -5. **Replacement**: Replaces all found occurrences with `new_string`. +2. **File Creation Mode**: If `old_string` is empty (`""`), creates the file with `new_string` as content (or appends if the file already exists), then stops. +3. **File Loading**: Reads the target file content. +4. **Uniqueness Check**: Counts occurrences of `old_string`. If the count doesn't match `expected_replacements` (default: 1), returns an error. +5. **Replacement**: Replaces the matched occurrence(s) with `new_string`. 6. **User Review**: Shows a preview of changes for user approval. 7. **Application**: Applies changes to the file if approved. 8. **Feedback**: Reports the number of replacements made. @@ -80,9 +83,9 @@ When the `edit_file` tool is invoked, it follows this process: ## Relation to Other Tools -- `edit_file`: Replaces **all occurrences** (this tool) +- `edit_file`: Replaces **exactly one** uniquely-identified occurrence by default; supports `old_string=""` file creation (this tool) - [`edit`](/advanced-usage/available-tools/edit): Replaces **first occurrence** only (unless `replace_all: true`) -- [`search_replace`](/advanced-usage/available-tools/search-replace): Also replaces **all occurrences** +- [`search_replace`](/advanced-usage/available-tools/search-replace): Also replaces **exactly one** uniquely-identified occurrence - [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching -These are different implementations of search-and-replace with varying default behaviors. +These are different implementations of search-and-replace with varying capabilities. diff --git a/docs/advanced-usage/available-tools/generate-image.md b/docs/advanced-usage/available-tools/generate-image.md index b230ba70..27fe4b3e 100644 --- a/docs/advanced-usage/available-tools/generate-image.md +++ b/docs/advanced-usage/available-tools/generate-image.md @@ -12,7 +12,7 @@ keywords: # generate_image -The `generate_image` tool creates new images from text prompts or modifies existing images using AI models through the OpenRouter API. This experimental feature enables visual content generation and transformation within your development workflow. +The `generate_image` tool creates new images from text prompts or modifies existing images using AI models. It supports two providers: **OpenRouter** and the **Roo provider**. This experimental feature enables visual content generation and transformation within your development workflow. --- @@ -48,14 +48,14 @@ This tool generates images from text descriptions or applies transformations to - **Image-to-image transformation**: Edit or transform existing images - Supports multiple input formats (PNG, JPG, JPEG, GIF, WEBP) - Automatic file extension handling -- Powered by OpenRouter API for access to various AI models +- Powered by **OpenRouter** or the **Roo provider** for access to various AI models - Experimental feature with ongoing improvements --- ## Limitations -- Requires OpenRouter API configuration +- Requires OpenRouter or Roo provider API configuration - Image quality depends on the AI model and prompt quality - Generation time varies based on complexity and model - Experimental feature: behavior may change in future releases @@ -72,7 +72,7 @@ When the `generate_image` tool is invoked, it follows this process: 2. **Mode Selection**: - If `image` parameter is provided: operates in **edit mode** (transform existing image) - Otherwise: operates in **generation mode** (create new image from prompt) -3. **API Request**: Sends request to OpenRouter API with prompt and optional input image. +3. **API Request**: Sends request to the configured provider (OpenRouter or Roo) with prompt and optional input image. 4. **Image Processing**: Receives generated/edited image from the API. 5. **File Saving**: Saves the image to the specified `path` with appropriate extension. 6. **Feedback**: Reports success and the location of the generated image. diff --git a/docs/advanced-usage/available-tools/read-file.md b/docs/advanced-usage/available-tools/read-file.md index c4d50b75..9bef96b5 100644 --- a/docs/advanced-usage/available-tools/read-file.md +++ b/docs/advanced-usage/available-tools/read-file.md @@ -28,16 +28,25 @@ The `read_file` tool accepts multiple files via the `args` format. Concurrency a ## Parameters -The tool accepts parameters in two formats depending on your configuration: +The tool accepts parameters in two formats: ### Standard Format (Single File) - `path` (required): The path of the file to read relative to the current working directory -- `start_line` (optional): The starting line number to read from (1-based indexing) -- `end_line` (optional): The ending line number to read to (1-based, inclusive) - -:::note Legacy Format -While the single-file parameters (`path`, `start_line`, `end_line`) are still supported for backward compatibility, we recommend using the newer `args` format for consistency and future compatibility. +- `mode` (optional): Reading mode — `"slice"` (default) or `"indentation"` +- `offset` (optional): 1-based line offset to start reading from (slice mode only, default: `1`) +- `limit` (optional): Maximum number of lines to return (slice mode only, default: `2000`) +- `indentation` (optional): Indentation-mode options — only used when `mode="indentation"`: + - `anchor_line` (required): 1-based line number to anchor the extraction. The tool extracts the complete semantic code block (function, class, method) containing this line. + - `max_levels` (optional): Maximum indentation levels to include above the anchor. + - `include_siblings` (optional): Whether to include sibling blocks at the same indentation level. + - `include_header` (optional): Whether to include file header content (imports, module-level comments) at the top of output. + - `max_lines` (optional): Hard cap on lines returned in indentation mode. + +:::note Mode Summary +- **Slice mode** (default): Reads lines sequentially from `offset` up to `limit` lines. Use for initial file exploration or reading a specific line range. +- **Indentation mode**: Extracts complete, syntactically valid code blocks around `anchor_line` based on indentation hierarchy. Preferred when you have a target line number (e.g., from search results or error messages) and need the entire function/class without mid-function truncation. +- **`start_line` and `end_line` do not exist** as parameters. Use `offset` and `limit` for range reads in slice mode. ::: ### Enhanced Format (Multi-File) @@ -147,7 +156,7 @@ When the `read_file` tool is invoked, it follows this process: The tool uses a clear decision hierarchy to determine how to read a file: 1. **First Priority: Explicit Line Range** - - Legacy single‑file format: both `start_line` and `end_line` must be provided for a range read; otherwise it reads normally. + - Single‑file format: specify `offset` and `limit` for a range read in slice mode, or use `anchor_line` in indentation mode. - Multi‑file `args` format: specify one or more `line_range` entries per file. - Range reads stream only the requested lines and bypass `maxReadFileLine`, taking precedence over other options. @@ -160,7 +169,7 @@ The tool uses a clear decision hierarchy to determine how to read a file: 3. **Third Priority: Automatic Truncation for Large Text Files** - Applies only when all of the following are true: - - Neither `start_line` nor `end_line` is specified. + - No `offset`/`limit` range is specified (slice mode) and no `anchor_line` is provided (indentation mode). - The file is identified as a text‑based file (not binary like PDF/DOCX/XLSX/IPYNB). - The file's total line count exceeds the `maxReadFileLine` setting (configurable; UI default may be 500; backend uses `-1`—no line limit—when unset). - When automatic truncation occurs: @@ -208,14 +217,14 @@ To read the complete content of a file: ### Reading Specific Lines -To read only a specific range of lines (e.g., 46-68): +To read only a specific range of lines (e.g., lines 46-68), use `offset` and `limit` in slice mode: **Input:** ```xml src/app.js -46 -68 +46 +23 ``` @@ -337,12 +346,12 @@ This behavior ensures that: - You receive guidance to use `line_range` for targeted reads - Stream errors are handled gracefully -**Example with line_range for targeted reading:** +**Example with offset/limit for targeted reading:** ```xml logs/massive-debug.log -1000 -1100 +1000 +101 ``` @@ -639,9 +648,9 @@ This allows Roo to analyze documentation, visual diagrams, configuration, and sp ## Troubleshooting - Range read returns error - - Cause: `start_line`/`end_line` invalid or `start_line > end_line` - - Fix: Provide both `start_line` and `end_line` as positive integers with `start_line ≤ end_line`; or use `args` with one or more `line_range` entries. - - Prevention: Prefer `line_range` in the multi‑file format for targeted reads. + - Cause: Invalid `offset` or `limit` values (e.g., non-positive integers). + - Fix: Use `offset` (1-based starting line) and `limit` (max lines to return) as positive integers in slice mode; or use `anchor_line` in indentation mode; or use the multi-file `args` format with `line_range` entries. + - Prevention: Prefer the multi-file `args` format with `line_range` for targeted reads across multiple files. - Large file returned a preview - Cause: File exceeded token budget or the large‑file tokenization threshold; a preview was returned. diff --git a/docs/advanced-usage/available-tools/search-replace.md b/docs/advanced-usage/available-tools/search-replace.md index 6403b3ae..a757298f 100644 --- a/docs/advanced-usage/available-tools/search-replace.md +++ b/docs/advanced-usage/available-tools/search-replace.md @@ -1,5 +1,5 @@ --- -description: Replace all occurrences of text in files using the search_replace tool in Roo Code. +description: Replace a uniquely-identified occurrence of text in a file using the search_replace tool in Roo Code. keywords: - search_replace - search and replace @@ -11,7 +11,7 @@ keywords: # search_replace -The `search_replace` tool performs search-and-replace operations on files, replacing **all occurrences** of specified text. It provides a straightforward way to make global text substitutions throughout a file. +The `search_replace` tool performs a targeted search-and-replace operation on a file, replacing **exactly one** uniquely-identified occurrence of specified text. If the search string matches multiple locations, the tool returns an error—the search string must be specific enough to identify a single target location. --- @@ -21,29 +21,30 @@ The tool accepts these parameters: - `file_path` (required): The path of the file to modify relative to the current working directory. - `old_string` (required): The exact text to search for and replace. -- `new_string` (required): The text to replace all occurrences with. +- `new_string` (required): The replacement text. --- ## What It Does -This tool searches for an exact string in a file and replaces **all occurrences** with new text. The replacement is performed globally across the entire file, making it ideal for consistent updates where every instance needs to change. +This tool searches for an exact string in a file and replaces **exactly one** occurrence with new text. The search string must uniquely identify the target location in the file. If multiple matches are found, the tool returns an error and requires a more specific search string to proceed. This is an intentional safety design to prevent unintended changes. --- ## When is it used? -- When replacing all instances of a string throughout a file -- When updating repeated string literals or configuration values -- When renaming variables, functions, or identifiers globally -- When fixing consistent patterns or outdated terminology -- When you need simple, exact string replacement for all matches +- When making a targeted change to a specific, uniquely identifiable location in a file +- When updating a specific string literal or configuration value at a known location +- When fixing a specific instance of a pattern or outdated terminology +- When you need simple, exact string replacement at a unique location +- When you need to ensure only one specific location is changed --- ## Key Features -- Replaces **all occurrences** globally (no option for single replacement) +- Replaces **exactly one** uniquely-identified occurrence per call +- Errors if multiple matches are found (intentional safety design) - Exact string matching (no regex or fuzzy matching) - Simple three-parameter interface - Shows preview of changes before applying @@ -55,9 +56,9 @@ This tool searches for an exact string in a file and replaces **all occurrences* ## Limitations - Requires exact string matches (case-sensitive, whitespace-sensitive) -- Always replaces all occurrences (cannot target specific instances) +- Errors if the search string matches more than one location (must be unique) - Cannot use regular expressions or patterns -- Not suitable for context-dependent replacements +- Not suitable for replacing all occurrences globally (use scripting for that) - Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits --- @@ -68,8 +69,8 @@ When the `search_replace` tool is invoked, it follows this process: 1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters. 2. **File Loading**: Reads the target file content. -3. **Search Operation**: Searches for all occurrences of `old_string` in the file. -4. **Replacement**: Replaces all found occurrences with `new_string`. +3. **Uniqueness Check**: Counts occurrences of `old_string` in the file. If more than one match is found, returns an error asking for a more specific search string. +4. **Replacement**: Replaces the single found occurrence with `new_string`. 5. **User Review**: Shows a preview of changes for user approval. 6. **Application**: Applies changes to the file if approved. 7. **Feedback**: Reports the result of the operation. @@ -78,8 +79,8 @@ When the `search_replace` tool is invoked, it follows this process: ## Relation to Other Tools -- `search_replace`: Always replaces **all occurrences** (this tool) -- [`edit_file`](/advanced-usage/available-tools/edit-file): Also replaces **all occurrences** (with optional expected count validation) +- `search_replace`: Replaces **exactly one** uniquely-identified occurrence (this tool) +- [`edit_file`](/advanced-usage/available-tools/edit-file): Also replaces **exactly one** occurrence by default; also supports `old_string=""` for file creation - [`edit`](/advanced-usage/available-tools/edit): Replaces **first occurrence** by default (unless `replace_all: true`) - [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching diff --git a/docs/advanced-usage/available-tools/skill.md b/docs/advanced-usage/available-tools/skill.md index b5b4aeb4..246020d8 100644 --- a/docs/advanced-usage/available-tools/skill.md +++ b/docs/advanced-usage/available-tools/skill.md @@ -56,10 +56,15 @@ This tool retrieves skill instructions from the skills directory and loads them When the `skill` tool is invoked, it follows this process: -1. **Skill Resolution**: Searches for the named skill in: - - Current mode's skill directory (e.g., `.roo/skills-code/`) - - Project-level skills (override global skills) - - Global skills directory +1. **Skill Resolution**: Searches for the named skill in the following locations (highest priority first): + - Project `.roo` mode-specific (e.g., `.roo/skills-code/`) + - Project `.roo` generic (`.roo/skills/`) + - Project `.agents` mode-specific (e.g., `.agents/skills-code/`) + - Project `.agents` generic (`.agents/skills/`) + - Global `.roo` mode-specific (e.g., `~/.roo/skills-code/`) + - Global `.roo` generic (`~/.roo/skills/`) + - Global `.agents` mode-specific (e.g., `~/.agents/skills-code/`) + - Global `.agents` generic (`~/.agents/skills/`) 2. **Skill Loading**: Loads the skill's main instruction file (typically `SKILL.md`). 3. **Context Injection**: Injects skill instructions into conversation context. 4. **Linked Files**: Files referenced in the skill are **not** automatically loaded; Roo must explicitly read them if needed. diff --git a/docs/advanced-usage/footgun-prompting.md b/docs/advanced-usage/footgun-prompting.md deleted file mode 100644 index a56f752b..00000000 --- a/docs/advanced-usage/footgun-prompting.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_label: 'Footgun Prompting' -description: Advanced guide to overriding system prompts in Roo Code. Learn how to customize AI behavior with caution using system prompt overrides. -keywords: - - footgun prompting - - system prompt override - - advanced customization - - Roo Code configuration - - custom prompts ---- - -# Footgun Prompting: Override System Prompts - -Footgun Prompting (System Prompt Override) lets you replace the default system prompt for a specific Roo Code mode. This offers granular control but bypasses built-in safeguards. Use with caution. - -Warning indicator for active system prompt override -**Warning Indicator:** When a system prompt override is active for the current mode, Roo Code will display a warning icon in the chat input area to remind you that the default behavior has been modified. - - -:::info **footgun** _(noun)_ - -1. _(programming slang, humorous, derogatory)_ Any feature likely to lead to the programmer shooting themself in the foot. - -> The System Prompt Override is considered a footgun because modifying the core instructions without a deep understanding can lead to unexpected or broken behavior, especially regarding tool usage and response consistency. - -::: - ---- - -## How It Works - -1. **Override File:** Create a file named `.roo/system-prompt-{mode-slug}` in your workspace root (e.g., `.roo/system-prompt-code` for the Code mode). -2. **Content:** The content of this file becomes the new system prompt for that specific mode. -3. **Activation:** Roo Code automatically detects this file. When present, it replaces most of the standard system prompt sections. -4. **Preserved Sections:** Only the core `roleDefinition` and any `customInstructions` you've set for the mode are kept alongside your override content. Standard sections like tool descriptions, rules, and capabilities are bypassed. -5. **Construction:** The final prompt sent to the model looks like this: - - ``` - ${roleDefinition} - - ${content_of_your_override_file} - - ${customInstructions} - ``` - ---- - -## Accessing the Feature - -Find the option and instructions in the Roo Code UI: - -1. Click the icon in the Roo Code top menu bar. -2. Expand the **"Advanced: Override System Prompt"** section. -3. Clicking the file path link within the explanation will open or create the correct override file for the currently selected mode in VS Code. - -UI showing the Advanced: Override System Prompt section - ---- - -## Using Context Variables - -When creating your custom system prompt file, you can use special variables (placeholders) that Roo Code will automatically replace with relevant information about the current environment. This allows you to make your prompts more dynamic and context-aware. - -Here are the available variables: - -- `{{mode}}`: The slug (short name) of the current Roo Code mode being used (e.g., `code`, `chat-mode`). -- `{{language}}`: The display language configured in VS Code (e.g., `en`, `es`). -- `{{shell}}`: The default terminal shell configured in VS Code (e.g., `/bin/bash`, `powershell.exe`). -- `{{operatingSystem}}`: The type of operating system your computer is running (e.g., `Linux`, `Darwin` for macOS, `Windows_NT`). -- `{{workspace}}`: The file path to the root of your current project workspace. - -**Example Usage:** - -You can include these variables directly in your prompt file content like this: - -``` -You are assisting a user in the '{{mode}}' mode. -Their operating system is {{operatingSystem}} and their default shell is {{shell}}. -The project is located at: {{workspace}}. -Please respond in {{language}}. -``` - -Roo Code substitutes these placeholders before sending the prompt to the model. - ---- - -## Key Considerations & Warnings - -- **Intended Audience:** Best suited for users deeply familiar with Roo Code's prompting system and the implications of modifying core instructions. -- **Impact on Functionality:** Custom prompts override standard instructions, including those for tool usage and response consistency. This can cause unexpected behavior or errors if not managed carefully. -- **Mode-Specific:** Each override file applies only to the mode specified in its filename (`{mode-slug}`). -- **No File, No Override:** If the `.roo/system-prompt-{mode-slug}` file doesn't exist, Roo Code uses the standard system prompt generation process for that mode. -- **Blank Files Ignored:** If the override file exists but is empty (blank), it will be ignored and the default system prompt will be used. -- **Directory Creation:** Roo Code ensures the `.roo` directory exists before attempting to read or create the override file. -Use this feature cautiously. Incorrect implementation can significantly degrade Roo Code's performance and reliability for the affected mode. \ No newline at end of file diff --git a/docs/advanced-usage/prompt-structure.md b/docs/advanced-usage/prompt-structure.md index 4832bca3..323d9cc9 100644 --- a/docs/advanced-usage/prompt-structure.md +++ b/docs/advanced-usage/prompt-structure.md @@ -45,10 +45,6 @@ The system prompt is the foundation of Roo's behavior. It contains: The system prompt is generated dynamically each time you interact with Roo, adapting to your current mode, available tools, and custom settings. -### Custom System Prompts - -Advanced users can create custom system prompts for specific modes by placing a `.roo/system-prompt-` file in their workspace. When present, Roo uses this file instead of generating the standard system prompt sections, allowing for complete customization of Roo's behavior in that mode. - --- ## User Messages @@ -103,7 +99,6 @@ Internally, Roo's prompt construction is handled by several components: - **System Prompt Generation**: The `SYSTEM_PROMPT` function in `src/core/prompts/system.ts` assembles the complete system prompt - **Section Generators**: Specialized functions create each section of the system prompt - **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API -- **Custom Prompt Loading**: The `loadSystemPromptFile` function checks for and processes custom system prompt files --- @@ -127,6 +122,5 @@ Understanding this structure can help you: - **Write Better Prompts**: Knowing what context Roo already has helps you avoid redundant information - **Troubleshoot Issues**: Understanding message flow helps identify where problems might occur - **Create Custom Modes**: With knowledge of the system prompt structure, you can create more effective custom modes -- **Use Custom System Prompts**: Advanced users can create entirely custom system prompts for specialized use cases This technical foundation powers all of Roo's capabilities, enabling it to understand your requests and effectively utilize available tools to complete tasks. \ No newline at end of file diff --git a/docs/basic-usage/using-modes.md b/docs/basic-usage/using-modes.md index f9e93381..6417b2e5 100644 --- a/docs/basic-usage/using-modes.md +++ b/docs/basic-usage/using-modes.md @@ -66,7 +66,7 @@ Four ways to switch modes: |--------|---------| | **Name** | `💻 Code` | | **Description** | A skilled software engineer with expertise in programming languages, design patterns, and best practices | -| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` | +| **Tool Access** | Full access to all tool groups: `read`, `edit`, `command`, `mcp` | | **Ideal For** | Writing code, implementing features, debugging, and general development | | **Special Features** | No tool restrictions—full flexibility for all coding tasks | @@ -76,7 +76,7 @@ Four ways to switch modes: |--------|---------| | **Name** | `❓ Ask` | | **Description** | A knowledgeable technical assistant focused on providing thorough and complete answers. It's less inclined to switch to implementing code unless explicitly requested and may use diagrams for clarification. | -| **Tool Access** | Limited access: `read`, `browser`, `mcp` only (cannot edit files or run commands) | +| **Tool Access** | Limited access: `read`, `mcp` only (cannot edit files or run commands) | | **Ideal For** | Code explanation, concept exploration, and technical learning | | **Special Features** | Optimized for detailed, informative responses, often using diagrams for clarity, without modifying your project. | @@ -86,7 +86,7 @@ Four ways to switch modes: |--------|---------| | **Name** | `🏗️ Architect` | | **Description** | An experienced technical leader and planner who helps design systems and create implementation plans | -| **Tool Access** | Access to `read`, `browser`, `mcp`, and restricted `edit` (markdown files only) | +| **Tool Access** | Access to `read`, `mcp`, and restricted `edit` (markdown files only) | | **Ideal For** | System design, high-level planning, and architecture discussions | | **Special Features** | Follows a structured approach from information gathering to detailed planning | @@ -96,7 +96,7 @@ Four ways to switch modes: |--------|---------| | **Name** | `🪲 Debug` | | **Description** | An expert problem solver specializing in systematic troubleshooting and diagnostics | -| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` | +| **Tool Access** | Full access to all tool groups: `read`, `edit`, `command`, `mcp` | | **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues | | **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues. Includes custom instructions to reflect, distill possibilities, add logs, and confirm before fixing. | @@ -121,7 +121,6 @@ Tailor Roo Code's behavior by customizing existing modes or creating new special Each tool group provides specific capabilities: - **`read`**: File reading, listing, and searching capabilities - **`edit`**: File modification and creation capabilities -- **`browser`**: Web browsing and search capabilities - **`command`**: Terminal command execution - **`mcp`**: Model Context Protocol server interactions diff --git a/docs/features/custom-modes.mdx b/docs/features/custom-modes.mdx index 582d73b6..6fa9a045 100644 --- a/docs/features/custom-modes.mdx +++ b/docs/features/custom-modes.mdx @@ -212,7 +212,6 @@ customModes: - - edit # First element of tuple - fileRegex: \.(md|mdx)$ # Second element is the options object description: Markdown files only - - browser - slug: another-mode name: Another Mode # ... other properties @@ -231,8 +230,7 @@ customModes: "customInstructions": "Focus on clarity and completeness in documentation.", "groups": [ "read", - ["edit", { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" }], - "browser" + ["edit", { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" }] ] }, { @@ -282,7 +280,7 @@ customModes: ##### `groups` * **Purpose:** Array/list defining which tool groups the mode can access and any file restrictions. -* **Available Tool Groups (Strings):** `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"`. +* **Available Tool Groups (Strings):** `"read"`, `"edit"`, `"command"`, `"mcp"`. * **Structure:** The `groups` property uses a specific structure: * Simple string for unrestricted access: `"edit"` * Tuple (two-element array) for restricted access: `["edit", { fileRegex: "pattern", description: "optional" }]` @@ -347,7 +345,6 @@ YAML is now the preferred format for defining custom modes due to several advant # Only allow reading files, no editing permissions groups: - read - - browser ``` * **Multi-line Strings:** YAML provides cleaner syntax for multi-line strings (e.g., for `roleDefinition` or `customInstructions`) using `|` (literal block) or `>` (folded block). ```yaml diff --git a/docs/features/experimental/concurrent-file-edits.md b/docs/features/experimental/concurrent-file-edits.md index 00ef4f9d..52c33cc6 100644 --- a/docs/features/experimental/concurrent-file-edits.md +++ b/docs/features/experimental/concurrent-file-edits.md @@ -1,12 +1,11 @@ --- sidebar_label: 'Multi-File Edits' -description: 'Speed up refactoring and multi-file changes with Roo Code''s experimental Concurrent File Edits feature. Edit multiple files in a single operation with batch approval.' +description: 'Speed up refactoring and multi-file changes with Roo Code''s Concurrent File Edits feature. Edit multiple files in a single operation with batch approval.' keywords: - concurrent file edits - multi-file edits - batch editing - refactoring - - "Roo Code experimental features" - apply_diff - "batch approval" --- @@ -78,26 +77,21 @@ When enabled, Roo automatically uses concurrent edits when appropriate. You'll s ## Technical Details -This feature leverages the [`apply_diff`](/advanced-usage/available-tools/apply-diff#experimental-multi-file-edits-multi_file_apply_diff) tool's experimental multi-file capabilities. For detailed information about the implementation, XML format, and how the `MultiFileSearchReplaceDiffStrategy` works, see the [apply_diff documentation](/advanced-usage/available-tools/apply-diff#experimental-multi-file-edits-multi_file_apply_diff). +This feature leverages the [`apply_diff`](/advanced-usage/available-tools/apply-diff) tool's multi-file capabilities. For detailed information about the implementation and diff format, see the [apply_diff documentation](/advanced-usage/available-tools/apply-diff). --- ## Best Practices -### When to Enable -- Using capable AI models (Claude 3.5 Sonnet, GPT-4, etc.) -- Comfortable reviewing multiple changes at once - -### When to Keep Disabled -- Working with less capable models that might struggle with complex multi-file contexts -- Prefer reviewing each change individually +- Use with capable AI models (Claude 3.5 Sonnet, GPT-4, etc.) for best results +- Review all proposed changes carefully before approving +- For very large batch operations, consider breaking the task into smaller chunks --- ## Limitations -- **Experimental**: This feature is still being refined and may have edge cases - **Model dependent**: Works best with more capable AI models - **Token usage**: Initial requests may use more tokens due to larger context - **Complexity**: Very large batch operations might be harder to review @@ -107,7 +101,6 @@ This feature leverages the [`apply_diff`](/advanced-usage/available-tools/apply- ## Troubleshooting ### Changes Not Batching -- Verify the experimental flag is enabled in settings - Check that your model supports multi-file operations - Ensure files aren't restricted by `.rooignore` diff --git a/docs/features/mcp/server-transports.md b/docs/features/mcp/server-transports.md index 5f4ce6eb..925941ef 100644 --- a/docs/features/mcp/server-transports.md +++ b/docs/features/mcp/server-transports.md @@ -114,10 +114,12 @@ Streamable HTTP transport is ideal for: Configuration in `settings.json`: ```json -"mcp.servers": { - "StreamableHTTPMCPName": { - "type": "streamable-http", - "url": "http://localhost:8080/mcp" +{ + "mcpServers": { + "StreamableHTTPMCPName": { + "type": "streamable-http", + "url": "http://localhost:8080/mcp" + } } } ``` diff --git a/docs/features/mcp/using-mcp-in-roo.mdx b/docs/features/mcp/using-mcp-in-roo.mdx index a41a55b4..71b28bc7 100644 --- a/docs/features/mcp/using-mcp-in-roo.mdx +++ b/docs/features/mcp/using-mcp-in-roo.mdx @@ -214,7 +214,7 @@ Streamable HTTP configuration example: SSE (Legacy) configuration parameters: - * `type` (optional, but recommended for clarity): Should be set to `"sse"` if providing a `url` for an SSE server, to distinguish from Streamable HTTP. If `url` is present and `type` is omitted, Roo Code might try to infer, but explicit declaration is safer. + * `type` (required for URL-based configs): Must be set to `"sse"` when using a `url` for an SSE server. For stdio configs (those using `command`), `type` defaults to `"stdio"` and can be omitted. For any URL-based config, omitting `type` will cause an immediate error—Roo Code cannot infer the transport type from a `url` alone. * `url` (required): The base URL for the remote MCP server. For legacy SSE, this usually implies separate paths like `/events` (for SSE stream) and `/message` (for POST requests) will be derived or expected by the server. * `headers` (optional): An object containing custom HTTP headers to send with requests (e.g., for authentication tokens). * `alwaysAllow` (optional): An array of tool names from this server to automatically approve. diff --git a/docs/features/model-temperature.md b/docs/features/model-temperature.md index 57f2ac8c..213919af 100644 --- a/docs/features/model-temperature.md +++ b/docs/features/model-temperature.md @@ -38,7 +38,7 @@ Temperature controls output randomness, not code quality or accuracy directly. K Roo Code uses a default temperature of 0.0 for most models, optimizing for maximum determinism and precision in code generation. This applies to OpenAI models, Anthropic models (non-thinking variants), LM Studio models, and most other providers. -Some models use higher default temperatures - DeepSeek R1 models and certain reasoning-focused models default to 0.6, providing a balance between determinism and creative exploration. +Some models use higher default temperatures - DeepSeek R1 models and certain reasoning-focused models default to 0.3, providing a balance between determinism and creative exploration. Models with thinking capabilities (where the AI shows its reasoning process) require a fixed temperature of 1.0 which cannot be changed, as this setting ensures optimal performance of the thinking mechanism. This applies to any model with the ":thinking" flag enabled. diff --git a/docs/features/skills.mdx b/docs/features/skills.mdx index 60df0f8c..9687ce13 100644 --- a/docs/features/skills.mdx +++ b/docs/features/skills.mdx @@ -71,16 +71,24 @@ This architecture means skills remain dormant until activated—they don't bloat **Global skills** (available in all projects): ```bash -# Linux/macOS +# Linux/macOS — Roo-specific (higher priority) ~/.roo/skills/{skill-name}/SKILL.md +# Linux/macOS — cross-agent (shared with other agent tools) +~/.agents/skills/{skill-name}/SKILL.md + # Windows %USERPROFILE%\.roo\skills\{skill-name}\SKILL.md +%USERPROFILE%\.agents\skills\{skill-name}\SKILL.md ``` **Project skills** (specific to current workspace): ```bash +# Roo-specific (higher priority) /.roo/skills/{skill-name}/SKILL.md + +# Cross-agent (shared with other agent tools) +/.agents/skills/{skill-name}/SKILL.md ``` #### 2. Create the skill directory and file @@ -146,7 +154,7 @@ Roo should recognize the request matches your skill description, load the SKILL. #### Basic structure ``` -~/.roo/skills/ # Global skills +~/.roo/skills/ # Global Roo-specific skills (high priority) ├── pdf-processing/ │ ├── SKILL.md # Required │ ├── extract.py # Optional: bundled scripts @@ -155,9 +163,17 @@ Roo should recognize the request matches your skill description, load the SKILL. └── api-docs-generator/ └── SKILL.md -.roo/skills/ # Project skills (override global) +~/.agents/skills/ # Global cross-agent skills (shared with other agent tools) +└── shared-workflow/ + └── SKILL.md + +.roo/skills/ # Project Roo-specific skills (override global) └── custom-pdf-workflow/ └── SKILL.md + +.agents/skills/ # Project cross-agent skills (shared with other agent tools) +└── team-shared-skill/ + └── SKILL.md ``` #### Mode-specific skills @@ -165,15 +181,19 @@ Roo should recognize the request matches your skill description, load the SKILL. Create skills that only activate in specific modes: ``` -~/.roo/skills-code/ # Only in Code mode +~/.roo/skills-code/ # Only in Code mode (Roo-specific, global) └── refactoring-patterns/ └── SKILL.md -.roo/skills-architect/ # Only in Architect mode +.roo/skills-architect/ # Only in Architect mode (Roo-specific, project) └── system-design-templates/ └── SKILL.md -~/.roo/skills-{modeSlug}/ # Any mode +~/.agents/skills-code/ # Only in Code mode (cross-agent, global) +└── shared-code-skill/ + └── SKILL.md + +.agents/skills-{modeSlug}/ # Mode-specific, cross-agent, project ``` **When to use mode-specific skills:** @@ -185,14 +205,18 @@ Create skills that only activate in specific modes: ## Override Priority -When skills with the same name exist in multiple locations, this priority applies (project vs global is evaluated first, then mode-specific vs generic within each source): +When skills with the same name exist in multiple locations, this priority applies (highest to lowest). `.roo/` paths always take precedence over `.agents/` paths at the same project level: -1. **Project mode-specific** (`.roo/skills-code/my-skill/`) -2. **Project generic** (`.roo/skills/my-skill/`) -3. **Global mode-specific** (`~/.roo/skills-code/my-skill/`) -4. **Global generic** (`~/.roo/skills/my-skill/`) +1. **Project `.roo` mode-specific** (`.roo/skills-code/my-skill/`) — highest priority +2. **Project `.roo` generic** (`.roo/skills/my-skill/`) +3. **Project `.agents` mode-specific** (`.agents/skills-code/my-skill/`) +4. **Project `.agents` generic** (`.agents/skills/my-skill/`) +5. **Global `.roo` mode-specific** (`~/.roo/skills-code/my-skill/`) +6. **Global `.roo` generic** (`~/.roo/skills/my-skill/`) +7. **Global `.agents` mode-specific** (`~/.agents/skills-code/my-skill/`) +8. **Global `.agents` generic** (`~/.agents/skills/my-skill/`) — lowest priority -This means a **project generic** skill overrides a **global mode-specific** skill—project location takes precedence over mode specificity. +A **project** skill always overrides a **global** skill of the same name. Within the same project level, `.roo/` overrides `.agents/`. This lets you: - Set global standards that work everywhere @@ -210,9 +234,6 @@ Roo automatically discovers skills: You don't need to register or configure skills—just create the directory structure. -:::warning Custom System Prompts Override Skills -If you have a file-based custom system prompt (`.roo/system-prompt-{mode-slug}`), it replaces the standard system prompt entirely—including the skills section. Skills won't be available when a custom system prompt is active. -::: #### Symlink support @@ -322,10 +343,11 @@ Roo Code skills follow the [Agent Skills](https://agentskills.io/) format for sk #### Roo-specific enhancements -Roo Code adds mode-specific targeting beyond the base format: +Roo Code adds mode-specific targeting and cross-agent compatibility beyond the base format: -- **Standard locations**: `.roo/skills/` and `~/.roo/skills/` -- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) enable mode targeting +- **Roo-specific locations**: `.roo/skills/`, `~/.roo/skills/` (higher priority) +- **Cross-agent locations**: `.agents/skills/`, `~/.agents/skills/` (shared with other agent tools) +- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) in both `.roo/` and `.agents/` paths enable mode targeting --- diff --git a/docs/update-notes/v3.14.0.md b/docs/update-notes/v3.14.0.md index 9573d55a..a5369cb3 100644 --- a/docs/update-notes/v3.14.0.md +++ b/docs/update-notes/v3.14.0.md @@ -36,7 +36,7 @@ This release introduces Gemini prompt caching, improves several tools, and inclu ## Footgun Prompting -* **Context Variables:** Added the ability to interpolate context variables (`{{workspace}}`, `{{mode}}`, `{{language}}`, `{{shell}}`, `{{operatingSystem}}`) into custom system prompt override files, allowing for more dynamic prompts (thanks daniel-lxs!). See the [Footgun Prompting documentation](/advanced-usage/footgun-prompting#using-context-variables) for details. +* **Context Variables:** Added the ability to interpolate context variables (`{{workspace}}`, `{{mode}}`, `{{language}}`, `{{shell}}`, `{{operatingSystem}}`) into custom system prompt override files, allowing for more dynamic prompts (thanks daniel-lxs!). * **Override Warning:** Roo Code now displays a warning indicator in the chat input when a system prompt override is active for the current mode. Warning indicator for active system prompt override diff --git a/docs/update-notes/v3.14.md b/docs/update-notes/v3.14.md index 2c144719..428256cb 100644 --- a/docs/update-notes/v3.14.md +++ b/docs/update-notes/v3.14.md @@ -79,7 +79,7 @@ keywords: ## Footgun Prompting -* **Context Variables:** Added the ability to interpolate context variables (`{{workspace}}`, `{{mode}}`, `{{language}}`, `{{shell}}`, `{{operatingSystem}}`) into custom system prompt override files, allowing for more dynamic prompts (thanks daniel-lxs!). See the [Footgun Prompting documentation](/advanced-usage/footgun-prompting#using-context-variables) for details. +* **Context Variables:** Added the ability to interpolate context variables (`{{workspace}}`, `{{mode}}`, `{{language}}`, `{{shell}}`, `{{operatingSystem}}`) into custom system prompt override files, allowing for more dynamic prompts (thanks daniel-lxs!). * **Override Warning:** Roo Code now displays a warning indicator in the chat input when a system prompt override is active for the current mode. Warning indicator for active system prompt override diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 4fea11b3..e765a1cd 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -184,10 +184,6 @@ const config: Config = { to: '/features/experimental/experimental-features', from: ['/features/experimental/power-steering'], }, - { - to: '/advanced-usage/footgun-prompting', - from: ['/features/footgun-prompting'], - }, { to: '/features/codebase-indexing', from: ['/features/experimental/codebase-indexing'], diff --git a/sidebars.ts b/sidebars.ts index 00a4cf06..a3b144ca 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -117,7 +117,6 @@ const sidebars: SidebarsConfig = { "advanced-usage/prompt-engineering", "advanced-usage/prompt-structure", "advanced-usage/rate-limits-costs", - "advanced-usage/footgun-prompting", "advanced-usage/roo-code-nightly", ], },