Prompt construction

docs/features/tools/tool-use-overview.md → docs/advanced-usage/available-tools/tool-use-overview.md

@@ -10,63 +10,63 @@ Tools are organized into logical groups based on their functionality:
 
 | Category | Purpose | Tools | Common Use |
 |----------|---------|-------|------------|
-| **Read Group** | File system reading and searching | [read_file](/features/tools/read-file), [search_files](/features/tools/search-files), [list_files](/features/tools/list-files), [list_code_definition_names](/features/tools/list-code-definition-names) | Code exploration and analysis |
-| **Edit Group** | File system modifications | [apply_diff](/features/tools/apply-diff), [insert_content](/features/tools/insert-content), [search_and_replace](/features/tools/search-and-replace), [write_to_file](/features/tools/write-to-file) | Code changes and file manipulation |
-| **Browser Group** | Web automation | [browser_action](/features/tools/browser-action) | Web testing and interaction |
-| **Command Group** | System command execution | [execute_command](/features/tools/execute-command) | Running scripts, building projects |
-| **MCP Group** | External tool integration | [use_mcp_tool](/features/tools/use-mcp-tool), [access_mcp_resource](/features/tools/access-mcp-resource) | Specialized functionality through external servers |
-| **Workflow Group** | Mode and task management | [switch_mode](/features/tools/switch-mode), [new_task](/features/tools/new-task), [ask_followup_question](/features/tools/ask-followup-question), [attempt_completion](/features/tools/attempt-completion) | Context switching and task organization |
+| **Read Group** | File system reading and searching | [read_file](/advanced-usage/available-tools/read-file), [search_files](/advanced-usage/available-tools/search-files), [list_files](/advanced-usage/available-tools/list-files), [list_code_definition_names](/advanced-usage/available-tools/list-code-definition-names) | Code exploration and analysis |
+| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [insert_content](/advanced-usage/available-tools/insert-content), [search_and_replace](/advanced-usage/available-tools/search-and-replace), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation |
+| **Browser Group** | Web automation | [browser_action](/advanced-usage/available-tools/browser-action) | Web testing and interaction |
+| **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command) | Running scripts, building projects |
+| **MCP Group** | External tool integration | [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool), [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) | Specialized functionality through external servers |
+| **Workflow Group** | Mode and task management | [switch_mode](/advanced-usage/available-tools/switch-mode), [new_task](/advanced-usage/available-tools/new-task), [ask_followup_question](/advanced-usage/available-tools/ask-followup-question), [attempt_completion](/advanced-usage/available-tools/attempt-completion) | Context switching and task organization |
 
 ### Always Available Tools
 
 Certain tools are accessible regardless of the current mode:
 
-- [ask_followup_question](/features/tools/ask-followup-question): Gather additional information from users
-- [attempt_completion](/features/tools/attempt-completion): Signal task completion
-- [switch_mode](/features/tools/switch-mode): Change operational modes
-- [new_task](/features/tools/new-task): Create subtasks
+- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question): Gather additional information from users
+- [attempt_completion](/advanced-usage/available-tools/attempt-completion): Signal task completion
+- [switch_mode](/advanced-usage/available-tools/switch-mode): Change operational modes
+- [new_task](/advanced-usage/available-tools/new-task): Create subtasks
 
 ## Available Tools
 
 ### Read Tools
 These tools help Roo understand your code and project:
 
-- [read_file](/features/tools/read-file) - Examines the contents of files
-- [search_files](/features/tools/search-files) - Finds patterns across multiple files
-- [list_files](/features/tools/list-files) - Maps your project's file structure
-- [list_code_definition_names](/features/tools/list-code-definition-names) - Creates a structural map of your code
+- [read_file](/advanced-usage/available-tools/read-file) - Examines the contents of files
+- [search_files](/advanced-usage/available-tools/search-files) - Finds patterns across multiple files
+- [list_files](/advanced-usage/available-tools/list-files) - Maps your project's file structure
+- [list_code_definition_names](/advanced-usage/available-tools/list-code-definition-names) - Creates a structural map of your code
 
 ### Edit Tools
 These tools help Roo make changes to your code:
 
-- [apply_diff](/features/tools/apply-diff) - Makes precise, surgical changes to your code
-- [insert_content](/features/tools/insert-content) - Adds new lines of content without modifying existing lines
-- [search_and_replace](/features/tools/search-and-replace) - Finds and replaces text or regex patterns within a file
-- [write_to_file](/features/tools/write-to-file) - Creates new files or completely rewrites existing ones
+- [apply_diff](/advanced-usage/available-tools/apply-diff) - Makes precise, surgical changes to your code
+- [insert_content](/advanced-usage/available-tools/insert-content) - Adds new lines of content without modifying existing lines
+- [search_and_replace](/advanced-usage/available-tools/search-and-replace) - Finds and replaces text or regex patterns within a file
+- [write_to_file](/advanced-usage/available-tools/write-to-file) - Creates new files or completely rewrites existing ones
 
 ### Browser Tools
 These tools help Roo interact with web applications:
 
-- [browser_action](/features/tools/browser-action) - Automates browser interactions
+- [browser_action](/advanced-usage/available-tools/browser-action) - Automates browser interactions
 
 ### Command Tools
 These tools help Roo execute commands:
 
-- [execute_command](/features/tools/execute-command) - Runs system commands and programs
+- [execute_command](/advanced-usage/available-tools/execute-command) - Runs system commands and programs
 
 ### MCP Tools
 These tools help Roo connect with external services:
 
-- [use_mcp_tool](/features/tools/use-mcp-tool) - Uses specialized external tools
-- [access_mcp_resource](/features/tools/access-mcp-resource) - Accesses external data sources
+- [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool) - Uses specialized external tools
+- [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) - Accesses external data sources
 
 ### Workflow Tools
 These tools help manage the conversation and task flow:
 
-- [ask_followup_question](/features/tools/ask-followup-question) - Gets additional information from you
-- [attempt_completion](/features/tools/attempt-completion) - Presents final results
-- [switch_mode](/features/tools/switch-mode) - Changes to a different mode for specialized tasks
-- [new_task](/features/tools/new-task) - Creates a new subtask
+- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question) - Gets additional information from you
+- [attempt_completion](/advanced-usage/available-tools/attempt-completion) - Presents final results
+- [switch_mode](/advanced-usage/available-tools/switch-mode) - Changes to a different mode for specialized tasks
+- [new_task](/advanced-usage/available-tools/new-task) - Creates a new subtask
 
 ## Tool Calling Mechanism
 
@@ -196,17 +196,17 @@ Tools are made available based on the current mode:
 
 1. **Information Gathering**
    ```
-   [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files)
+   [ask_followup_question](/advanced-usage/available-tools/ask-followup-question) → [read_file](/advanced-usage/available-tools/read-file) → [search_files](/advanced-usage/available-tools/search-files)
    ```
 
 2. **Code Modification**
    ```
-   [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion)
+   [read_file](/advanced-usage/available-tools/read-file) → [apply_diff](/advanced-usage/available-tools/apply-diff) → [attempt_completion](/advanced-usage/available-tools/attempt-completion)
    ```
 
 3. **Task Management**
    ```
-   [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command)
+   [new_task](/advanced-usage/available-tools/new-task) → [switch_mode](/advanced-usage/available-tools/switch-mode) → [execute_command](/advanced-usage/available-tools/execute-command)
    ```
 
 ## Error Handling and Recovery

docs/advanced-usage/prompt-structure.md

@@ -0,0 +1,106 @@
+# Prompt Structure
+
+This page explains the technical structure of prompts in Roo Code - how messages are constructed and sent to the Large Language Model (LLM).
+
+## Core Message Types
+
+Roo Code uses three primary message types when communicating with LLMs:
+
+- **System Prompt**: The initial instructions that define Roo's capabilities, persona, and operational rules
+- **User Messages**: Content sent by you (the user) to Roo
+- **Assistant Messages**: Responses generated by the LLM based on your requests
+
+At the API level, there's also a fourth message role:
+
+- **Tool Messages**: Results returned from tool executions, sent back to the LLM as input
+
+Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization.
+
+## System Prompt
+
+The system prompt is the foundation of Roo's behavior. It contains:
+
+- **Role Definition**: The core persona instructions based on the selected mode (Code, Ask, Debug, etc.)
+- **Tool Descriptions**: Detailed information about available tools, including parameters and examples
+- **Tool Use Guidelines**: Rules for how tools should be used (sequential execution, waiting for results)
+- **Capabilities**: Description of what Roo can do in the current environment
+- **Available Modes**: List of all available modes and their descriptions
+- **Operational Rules**: Critical guidelines for handling files, project structure, and user interaction
+- **System Information**: Details about your environment (OS, shell, working directory)
+- **Custom Instructions**: Your global and mode-specific customizations
+
+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-<mode_slug>` 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
+
+User messages contain your direct inputs to Roo, plus additional contextual information:
+
+- **Your Query**: The text you type in the chat interface
+- **Images**: Any images you include in your message (for supported models)
+- **Environment Details**: Automatically appended information about your workspace state:
+  - Open files/tabs
+  - Cursor position
+  - Active terminals with output
+  - Recently modified files
+  - Current time
+  - Token/cost information
+  - Current mode
+  - File listing (on initial connection)
+
+This automatic context enrichment helps Roo understand your workspace without requiring you to explicitly describe it.
+
+## Assistant Messages
+
+Assistant messages are the LLM's responses, which may include:
+
+- **Text Responses**: Direct answers to your queries
+- **Thinking**: Internal reasoning process (visible when enabled)
+- **Tool Calls**: Requests to use specific tools like reading files or executing commands
+
+Note that while assistant messages contain tool calls, the results of those tools are sent back to the LLM in separate tool messages, not as part of the assistant message itself.
+
+## Message Flow
+
+Here's how these components work together:
+
+1. **Initial Setup**: Roo generates the system prompt based on your selected mode and configuration
+2. **User Input**: You send a message, which is enriched with environment details
+3. **LLM Processing**: The LLM receives all previous messages plus your new input
+4. **Assistant Response**: The LLM generates a response, potentially using tools
+5. **Tool Execution**: If the LLM requests a tool, Roo executes it and provides the result
+6. **Conversation History**: All messages are maintained in a structured history for context
+
+## Technical Implementation
+
+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
+
+## Support Prompts
+
+Alongside the main chat flow, Roo uses specialized templates for specific code actions:
+
+- **Code Action Prompts**: For commands like "Explain", "Fix", "Improve", or "Add to Context"
+- **Template-Based**: Generated from templates in `src/shared/support-prompt.ts`
+- **Independent Context**: Often operates without the main chat history
+- **Task-Specific Format**: Optimized for the specific code task being performed
+
+These support prompts work outside the normal conversation flow to provide focused assistance for specific coding tasks.
+
+## Optimizing Your Interactions
+
+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.

docs/basic-usage/how-tools-work.md

@@ -80,4 +80,4 @@ This safety mechanism ensures you maintain control over which files are modified
 
 ## Learn More About Tools
 
-For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/features/tools/tool-use-overview) documentation.
+For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/advanced-usage/available-tools/tool-use-overview) documentation.

docs/basic-usage/using-modes.md

@@ -79,15 +79,15 @@ Four ways to switch modes:
 | **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. |
 
-### Orchestrator Mode (aka [Boomerang Mode](/features/boomerang-tasks))
+### Orchestrator Mode (aka Boomerang Mode)
 
 | Aspect | Details |
 |--------|---------|
 | **Name** | `🪃 Orchestrator` |
 | **Description** | A strategic workflow orchestrator (aka Boomerang Mode) that breaks down complex tasks and delegates them to specialized modes |
 | **Tool Access** | Access to `read`, `browser`, `command`, `mcp`, and restricted `edit` (mode configuration files only: `.roomodes`, `custom_modes.json`) |
 | **Ideal For** | Managing multi-step projects, coordinating work across different modes, and automating complex workflows |
-| **Special Features** | Uses the [`new_task`](/features/tools/new-task) tool to delegate subtasks to other modes. See [Boomerang Tasks](/features/boomerang-tasks) for details. |
+| **Special Features** | Uses the [`new_task`](/advanced-usage/available-tools/new-task) tool to delegate subtasks to other modes. |
 
 ## Custom Modes
 

docs/features/boomerang-tasks.mdx

@@ -60,6 +60,6 @@ Use subtasks (delegated via Orchestrator mode) to maintain clarity. If a request
 :::
 
 
-[^1]: This context is passed via the `message` parameter of the [`new_task`](/features/tools/new-task) tool when the Orchestrator mode delegates the task.
-[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/features/tools/new-task) tool during initiation by the Orchestrator mode.
-[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/features/tools/attempt-completion) tool when the subtask finishes.
+[^1]: This context is passed via the `message` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool when the Orchestrator mode delegates the task.
+[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool during initiation by the Orchestrator mode.
+[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/advanced-usage/available-tools/attempt-completion) tool when the subtask finishes.

docs/features/experimental/experimental-features.md

@@ -18,14 +18,6 @@ To enable or disable experimental features:
 
 The following experimental features are currently available:
 
-### Search and Replace
-
-Adds a new tool for searching and replacing text in a file.
-
-### Insert Content
-
-Adds a new tool for inserting content at any position in a file.
-
 ### Power Steering
 
 When enabled, Roo will remind the model about the details of its current mode definition more frequently. This will lead to stronger adherence to role definitions and custom instructions, but will use more tokens per message.

docs/features/fast-edits.md

@@ -19,7 +19,7 @@ When **Enable editing through diffs** is checked:
 2.  **Prevents Truncated Writes**: The system automatically detects and rejects attempts by the AI to write incomplete file content, which can happen with large files or complex instructions. This helps prevent corrupted files.
 
 :::note Disabling Fast Edits
-If you uncheck **Enable editing through diffs**, Roo will revert to writing the entire file content for every edit using the [`write_to_file`](/features/tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/features/tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage.
+If you uncheck **Enable editing through diffs**, Roo will revert to writing the entire file content for every edit using the [`write_to_file`](/advanced-usage/available-tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/advanced-usage/available-tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage.
 :::
 
 ## Match Precision

docs/features/shell-integration.md

@@ -6,7 +6,7 @@ Terminal Shell Integration is a key feature that enables Roo Code to execute com
 
 Shell integration is automatically enabled in Roo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Roo to:
 
-- Execute commands on your behalf through the [`execute_command`](/features/tools/execute-command) tool
+- Execute commands on your behalf through the [`execute_command`](/advanced-usage/available-tools/execute-command) tool
 - Read command output in real-time without manual copy-pasting
 - Automatically detect and fix errors in running applications
 - Observe command exit codes to determine success or failure