Merge branch 'RooCodeInc:main' into main

Author: SannidhyaSah

.roomodes

@@ -1,17 +1,5 @@
 {
   "customModes": [
-    {
-      "slug": "docs",
-      "name": "Documentation Writer",
-      "roleDefinition": "You are a technical documentation writer who is a seasoned, straightforward, and technically precise expert who prioritizes clarity and efficiency. With 24 years of coding and documentation writing experience, you have a natural conversational style that values concise, no-nonsense communication. Your approach is authentic and candid, focusing relentlessly on user comprehension without overselling features or using ambiguous language. You avoid fluff, ensuring every sentence provides clear value, practical guidance, or actionable steps. The tone remains professional yet approachable, fostering immediate trust through reliability and transparency. You specialize in writing technical documentation for the Visual Studio Code extension Roo Code, using Docusaurus to structure, format, and publish content efficiently. With deep expertise in Markdown and MDX, you optimize documentation for readability, accessibility, and seamless navigation within a static-site environment built on React. It is important to ensure the content is accessible to readers with varying technical proficiencies, including those who may have learning disabilities such as ADD/ADHD, by maintaining clear structure, logical flow, and avoiding unnecessary complexity.",
-      "customInstructions": "### Custom Instructions\n\n1. **Directness and Clarity**  \n   Begin each documentation entry with the most important information users need, avoiding introductory filler or unnecessary context.\n\n2. **Precision and Brevity**  \n   Favor short, precise explanations and actionable steps. Users should swiftly grasp concepts without requiring additional clarification.\n\n3. **Authentic and Natural Tone**  \n   Write in a conversational style that reflects Roo's straightforward, reliable, and trustworthy personality—avoiding marketing jargon or generic phrases.\n\n4. **Practical Examples**  \n   Include realistic examples aimed at experienced developers. Provide accurate, concise code snippets ready for immediate use, avoiding trivial or clichéd demos.\n\n5. **Consistent Formatting**  \n   Use structured headings, bullet points, and brief paragraphs for easy scanning and comprehension.\n\n6. **Avoid Over-explaining**  \n   Assume a reasonable level of technical competence. Do not elaborate on basic coding concepts unless it’s essential to clarify a unique Roo Code feature.\n\n7. **Proactive Anticipation**  \n   Address likely questions or pitfalls within the relevant sections. Incorporate tips or clarifications to prevent common mistakes.\n\n8. **Minimalism in Wording**  \n   Eliminate unnecessary adjectives, adverbs, or verbose descriptions. Use clear, functional language that reduces cognitive load.\n\n9. **Internal Links**  \n   Always use **absolute paths starting from the `/docs/` root** for internal links, and **omit the `.md` file extension**.  \n   Example:  \n   ```md\n   [Link to Guide](/intro/)\n\n\t10.\t@site Alias\n\t•\tFor code imports or special references that need to resolve from the project root, use the @site alias.\n\t•\tExample:\n\nimport Header from '@site/src/components/Header';\n\n\n\t•\tAvoid @site in Markdown links—use absolute paths instead.\n\n\t11.\tCode Examples\nProvide clearly formatted code snippets suitable for copy-pasting. Maintain consistent syntax highlighting, indentation, and structure.\n\t12.\tImages\nInsert an image placeholder where needed. Include a brief description of the image below the placeholder. The final image element should follow this format (folder name may vary):\n\n<img src=\"/img/installing/installing-2.png\" alt=\"VS Code's Install from VSIX dialog\" width=\"600\" />\n\n(with the folder starting at /img/)",
-      "groups": [
-        "read",
-        "command",
-        "edit"
-      ],
-      "source": "project"
-    },
     {
       "slug": "video-script-writer",
       "name": "Video Script Writer",
@@ -30,6 +18,18 @@
         "edit"
       ],
       "source": "project"
+    },
+    {
+      "slug": "docs",
+      "name": "Documentation Writer",
+      "roleDefinition": "You are a technical documentation writer who is a seasoned, straightforward, and technically precise expert who prioritizes clarity and efficiency. With 24 years of coding and documentation writing experience, you have a natural conversational style that values concise, no-nonsense communication. Your approach is authentic and candid, focusing relentlessly on user comprehension without overselling features or using ambiguous language. You avoid fluff, ensuring every sentence provides clear value, practical guidance, or actionable steps. The tone remains professional yet approachable, fostering immediate trust through reliability and transparency. You specialize in writing technical documentation for the Visual Studio Code extension Roo Code, using Docusaurus to structure, format, and publish content efficiently. With deep expertise in Markdown and MDX, you optimize documentation for readability, accessibility, and seamless navigation within a static-site environment built on React. It is important to ensure the content is accessible to readers with varying technical proficiencies, including those who may have learning disabilities such as ADD/ADHD, by maintaining clear structure, logical flow, and avoiding unnecessary complexity.",
+      "customInstructions": "Custom Instructions (Plain Text)\n\n1. Directness and Clarity\nStart each documentation entry with the most important information. Skip introductory filler or unnecessary background.\n\n2. Precision and Brevity\nKeep explanations short and focused. Prioritize actionable steps and concise guidance.\n\n3. Authentic and Natural Tone\nUse a conversational, trustworthy tone that reflects Roo’s straightforward style.\nAvoid: marketing jargon, buzzwords, and generic terms like \"seamless\", \"intuitive\", \"state-of-the-art\", \"revolutionary\", or \"robust\".\nUse: plain, specific language developers recognize and respect.\n\n4. Practical Examples\nUse real-world examples aimed at experienced developers. Include clear, usable code snippets and avoid simplistic or clichéd demos.\n\n5. Consistent Formatting\nApply structured headings, bullet lists, and short paragraphs to improve scannability.\n\n6. Avoid Over-explaining\nAssume users know the basics. Only explain foundational concepts if they’re necessary to understand Roo-specific features.\n\n7. Proactive Anticipation\nPreempt common mistakes or confusion. Add relevant tips or notes directly where needed.\n\n8. Minimalism in Wording\nCut fluff. Drop unnecessary adjectives, adverbs, and verbose phrasing. Stick to efficient, functional wording.\n\n9. Internal Links\nUse absolute paths that start from /docs/, and don’t include the .md file extension.\nExample:\n[Link to Guide](/intro/)\n\n10. @site Alias\n- Use @site for code imports or special references from the project root.\n  Example:\n  import Header from '@site/src/components/Header';\n- Don’t use @site in Markdown links. Stick with absolute paths.\n\n11. Code Examples\nProvide well-formatted code that’s ready to copy-paste. Use consistent indentation, syntax, and style.\n\n12. Images\nInsert placeholders where images belong, with a short description below. Use this format (adjust folder as needed):\n<img src=\"/img/installing/installing-2.png\" alt=\"VS Code's Install from VSIX dialog\" width=\"600\" />\nImages should live under /img/.",
+      "groups": [
+        "read",
+        "command",
+        "edit"
+      ],
+      "source": "project"
     }
   ]
 }

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

@@ -70,6 +70,21 @@ These tools help manage the conversation and task flow:
 
 ## Tool Calling Mechanism
 
+### Handling Complex Tasks
+
+For certain complex operations that require multiple steps, Roo doesn't just figure them out on the fly. Instead, it follows predefined, internal plans to ensure consistency and accuracy.
+
+A prime example is creating a new MCP server, identified internally by `create_mcp_server`. **This identifier does not represent a tool you will see being called.** Rather, when you ask Roo to create a server, it triggers this known, multi-step workflow.
+
+This specific workflow is initiated by Roo using its internal `fetch_instructions` tool (with the task `create_mcp_server`) to retrieve a detailed plan. This plan then guides Roo to make calls to several standard, documented tools in sequence, such as:
+
+*   [`execute_command`](/advanced-usage/available-tools/execute-command) for running setup scripts (e.g., `npx @modelcontextprotocol/create-server`).
+*   [`write_to_file`](/advanced-usage/available-tools/write-to-file) or [`apply_diff`](/advanced-usage/available-tools/apply-diff) for creating or modifying server code and configuration files.
+*   [`ask_followup_question`](/advanced-usage/available-tools/ask-followup-question) to gather necessary information like API keys from you.
+*   Other standard tools as needed for steps like determining file locations or updating configuration entries.
+
+So, while the overall task (like `create_mcp_server`) is complex, it's ultimately accomplished by intelligently orchestrating the standard tools available in your environment. This approach allows Roo to reliably perform complex operations by leveraging the tools documented here.
+
 ### When Tools Are Called
 
 Tools are invoked under specific conditions:

docs/advanced-usage/context-poisoning.md

@@ -0,0 +1,56 @@
+# Context Poisoning
+
+:::info
+Context poisoning is a persistent issue within a given session. Once a chat session's context is compromised, treat that session as disposable. Starting fresh with a clean context is crucial for maintaining the accuracy and effectiveness of your Roo Code agent.
+:::
+
+Context poisoning occurs when inaccurate or irrelevant data contaminates the language model's active context. This leads the model to draw incorrect conclusions, provide erroneous information to tools, and progressively deviate from the intended task with each interaction.
+
+## Symptoms of Context Poisoning
+
+Identify context poisoning by observing these behaviors:
+
+*   **Degraded Output Quality:** Suggestions become nonsensical, repetitive, or irrelevant.
+*   **Tool Misalignment:** Tool calls no longer correspond to the user's requests.
+*   **Orchestration Failures:** Orchestrator chains may stall, loop indefinitely, or fail to complete.
+*   **Temporary Fixes:** Re-applying a clean prompt or instructions offers only brief respite before issues resurface.
+*   **Tool Usage Confusion:** The model struggles to correctly use or recall how to use tools defined in the system prompt.
+
+## Common Causes
+
+Context poisoning can be triggered by several factors:
+
+*   **Model Hallucination:** The model generates an incorrect piece of information and subsequently treats it as a factual part of the context.
+*   **Code Comments:** Outdated, incorrect, or ambiguous comments in the codebase can be misinterpreted by the model, leading it down the wrong path.
+*   **Contaminated User Input:** Copy-pasting logs or text containing hidden or rogue control characters.
+*   **Context Window Overflow:** As a session grows, older, useful information may be pushed out of the model's limited context window, allowing "poisoned" data to have a greater relative impact.
+
+Once bad data enters the context, it tends to persist. The model re-evaluates this tainted information in subsequent reasoning cycles, similar to a permanent flaw affecting its perception until the context is completely reset.
+
+## Can a "Wake-Up Prompt" Resolve Context Poisoning?
+
+**Short Answer:** No.
+
+A corrective prompt might temporarily suppress symptoms, but the problematic data remains in the conversational buffer. The model will likely revert to the poisoned state as soon as the interaction deviates from the narrow scope of the corrective prompt.
+
+**Detailed Explanation:**
+
+*   Re-injecting the full set of tool definitions or core directives can sometimes mask the damage for one or some interactions following the initial context poisoning .
+*   However, the underlying poisoned context remains. Any query or task outside the immediate "patch" will likely re-trigger the original issue.
+*   This approach is unreliable, akin to placing a warning label on a leaking pipe instead of repairing it.
+
+## Effective Recovery Strategies
+
+To reliably recover from context poisoning:
+
+*   **Hard Reset the Session:** The most dependable solution is to start a new chat session. This clears the contaminated context entirely.
+*   **Minimize Manual Data Dumps:** When pasting logs or other data, be selective. Only include the essential information the model requires.
+*   **Manage Context Window Size:** For large or complex tasks, consider breaking them into smaller, focused chat sessions. This helps ensure that stale or irrelevant information ages out of the context window more quickly.
+*   **Validate Tool Output:** If a tool returns nonsensical or clearly incorrect data, delete that message from the chat history before the model can process it and incorporate it into its context.
+
+## Addressing a Common Question: The "Magic Bullet" Prompt
+
+A frequent question from the community is:
+> "Have you found a prompt that wakes it back up? Maybe a prompt that just has the tools instructions we can push back in manually?”
+
+As explained, no single prompt offers a lasting fix. Any immediate improvement is superficial because the corrupted lines of text persist in the session's history, ready to cause further issues. The only robust solution is to discard the compromised session, initiate a new one, and provide it with a clean prompt and the correct tool definitions from the outset.

docs/community/index.md

@@ -11,6 +11,7 @@ Welcome to the Roo Code community section! Here you'll find community projects t
 | [Tips & Tricks](/community/tips-and-tricks) | Collection of files designed to supercharge your Roo Code experience and maximize productivity |
 | [Dynamic Rules](/community/dynamic-rules) | Define new rules and delete them on the fly with simple syntax in your messages |
 | [Roo Commander](/community/roo-commander) | Sophisticated collection of custom modes designed to manage software development projects |
+| [Maestro Project](/community/maestro) | Orchestrates a team of specialized modes for comprehensive software development lifecycle management |
 
 ## Custom Modes Gallery {#custom-modes-gallery}
 

docs/community/maestro.md

@@ -0,0 +1,16 @@
+# Maestro Project by shariqriazz
+
+[View Project on GitHub](https://github.com/shariqriazz/maestro)
+
+The Maestro Project provides a comprehensive system of highly specialized Roo modes designed to work together as an integrated development team. Orchestrated by the central **Maestro** mode, this system manages the entire software development lifecycle by delegating tasks to modes with deep expertise in specific domains such as planning, design, frontend/backend development, database management, DevOps, testing, and documentation.
+
+## Key Concepts
+
+- **Central Orchestration**: The Maestro mode analyzes user requests, decomposes tasks, and delegates them to the most appropriate specialized mode.
+- **Specialized Modes**: A collection of over 30 modes, each an expert in a narrow field (e.g., Visionary for architecture, ReactMaster for React development, SqlMaster for SQL databases).
+- **Structured Workflow**: Employs defined protocols for task delegation, context management, progress tracking, quality assurance, and inter-mode collaboration.
+- **Interaction Modes**: Offers different interaction styles (e.g., `YOLO MVP`, `Follow Production`) to control the autonomy and thoroughness of the specialized modes.
+- **Extensible System**: Designed to be extended with new specialized modes as needed.
+- **Prerequisites**: Relies on the [Maestro Mode Repository](https://github.com/shariqriazz/maestro) and potentially the [Vertex AI MCP Server](https://github.com/shariqriazz/vertex-ai-mcp-server) for full functionality of certain modes like the Researcher.
+
+This system aims to enhance development consistency, quality, and coverage by leveraging a team of virtual specialists.