DOCSEARCHbyAlgolia
Submit Docs

Custom Modes for Roo Code

repository·main·Indexed 41 days ago

https://github.com/jtgsystems/custom-modes-roo-code

A professional library of 225 specialized AI agent configurations for Roo Code, optimized for 2026 development standards. It provides personas across domains including AI/ML, DevOps, Security, and SOTA reasoning. The collection includes tools for managing per-mode YAML files, validating configurations against a JSON schema, and a conversion utility (`convert_modes.py`) to transform YAML agents into the VS Code extension format.

Tokens
8.9K
Snippets
20
Records
37
Agent score
52%

What's inside Custom Modes Roo Code

  1. Overview of Researched Agents for Improvement

    main

    This document tracks the research and improvement status of agents located in the agents/ directory of the Custom-Modes-Roo-Code repository. It serves as a roadmap for enhancing agent capabilities through modern technology stacks and industry best practices.

    Status Indicators:

    • [ ] Pending: The agent has not yet been researched for improvements.
    • [-] In Progress: Research or implementation is currently underway.
    • [x] Completed: The agent has been enhanced with specific technical updates and notes.

  2. Understand the SOTA 2026 Security Audit Playbook structure

    main

    The SOTA 2026 Security Audit Playbook is a canonical reference injected into security-focused agent personas within the custom-modes-roo-code repository. It provides a structured framework for security audits and adversarial hardening.

    When using a security agent equipped with this playbook, expect the agent to follow these core principles:

    • Systemic Mandate: Operates under pervasive distrust, assumes hostile deployment, and prioritizes chaining vulnerabilities over isolated findings.
    • Thinking Protocol: Uses reasoning transparency via explicit ANALYSIS blocks.
    • Confidence Scoring: Categorizes findings from CONFIRMED down to INFORMATIONAL.
    • Audit Scope: Covers Code, Data, Auth, Network, Cloud, CI/CD, Supply Chain, and AI/ML.
    • Threat Modeling: Utilizes 9 Attacker Profiles, MITRE ATT&CK mapping, and STRIDE/DFD.
    • Vulnerability Analysis: Targets Auth, Injection, XSS, CSRF, File Upload, Crypto, API, and Business Logic.
    • LLM/AI Security: Specifically addresses Prompt Injection, RAG, Model Security, and Agent Safety.
    • Output Format: Generates an Executive Summary, detailed Findings, Attack Chains, and a Remediation Roadmap.
    • Self-Correction: Employs a 5-round final review loop to ensure accuracy.

  3. How the mode conversion works

    main

    The conversion tool transforms CLI-format modes into VS Code-compatible formats by mapping specific fields and restructuring instructions.

    Data Transformation

    Field Mapping:

    • The CLI customInstructions field is extracted and moved into a dedicated XML file located at .roo/rules-{slug}/1_instructions.xml.
    • The VS Code format requires a whenToUse field; if not present in the source, the script provides default text.

    Format Comparison:

    CLI Format (Source):

    customModes:
  - slug: code-skeptic
    name: 🧐 Code Skeptic
    roleDefinition: You are a SKEPTICAL...
    customInstructions: "You will: 1. NEVER ACCEPT..."
    groups: [read, edit, browser, command, mcp]

    VS Code Format (Target):

    customModes:
  - slug: code-skeptic
    name: 🧐 Code Skeptic
    roleDefinition: You are a SKEPTICAL...
    whenToUse: Use when you need to act as a 🧐 Code Skeptic...
    groups: [read, edit, browser, command, mcp]

    Limitations

    • No Semantic XML: The script converts plain text instructions into a single XML file. It cannot automatically create semantic structures like <workflow>, <step>, or <actions>.
    • Manual Enhancement Recommended: For high-quality modes, users should manually split the generated 1_instructions.xml into multiple structured XML files (e.g., 1_workflow.xml, 2_quality_gates.xml) to leverage VS Code's rich XML capabilities.

  4. Apply the SOTA 2026 Debugging Philosophy

    main

    When debugging with an AI agent or manually, adhere to these core principles to avoid stacked fixes on broken foundations:

    • Isolate pure state from side effects: Use Occam's Razor to eliminate typos, missing imports, stale caches, and environment variable errors first.
    • Enforce counterfactual isolation: Change exactly one variable per experiment. If two changes fix a bug, the root cause is still unknown.
    • Prioritize reproducibility: Reproduce the bug in a minimal, deterministic environment before attempting any fix.
    • Use assertions: Insert assertions for every invariant to ensure the system crashes early and loudly upon violation.
    • Practice delta debugging: Minimize failing inputs and use time-travel debugging (record & replay) where available.
    • Apply the Five Whys: Use this technique to move past symptoms to the true root cause.

  5. Search and list available custom modes

    main

    The conversion tool provides utilities to explore the available mode library before conversion.

    List all modes

    Displays all available modes organized alphabetically:

    python3 convert_modes.py list

    Search for modes

    Search using wildcard patterns (*). You can search by slug or name, and provide multiple patterns.

    Search with wildcards:

    python3 convert_modes.py search code*
python3 convert_modes.py search *python* *architect*

    Search multiple patterns:

    python3 convert_modes.py search golang* rust* *developer*
    python3 convert_modes.py search code*

  6. Fix common custom mode quality issues

    main

    When reviewing custom modes, address these four specific issues:

    1. Identical description and roleDefinition: Split them. The description should be a concise 80-150 character summary. The roleDefinition should be a detailed 300-800 character persona with domain expertise.
    2. Short roleDefinition (< 150 chars): Expand the persona by including specific methodologies, tools, quality standards, and concrete responsibilities.
    3. Placeholder whenToUse: Replace generic text like "Use when you need X expertise" with specific scenarios, problems the mode solves, and when NOT to use it.
    4. Weak customInstructions: Enhance generic instructions with step-by-step workflows, decision trees, quality checkpoints, or tool-specific guidance.
    # GOOD EXAMPLE
description: Systematically isolates root causes of runtime failures through
  tracing, reproduction, and evidence-based analysis.
roleDefinition: >-
  You are an expert debugging specialist who eliminates unknowns to find root
  causes. You combine static analysis, dynamic tracing, and environmental
  inspection. You produce minimal reproduction cases, write regression tests, 
  and document failure modes. You understand memory corruption, race 
  conditions, deadlocks, and Heisenbugs.
whenToUse: >-
  Activate when investigating crashes, flaky tests, memory leaks, or any
  behavior that deviates from expected output. Also use when logs or stack
  traces need expert interpretation.

  7. Install Custom Modes via Selective Installation

    main

    If you only need specific categories or the SOTA personas, you can copy them directly to your .roo-code/agents/ directory.

    Install specific category:

    cp agents/core-development ~/.roo-code/agents/ -r

    Install SOTA personas only:

    cp agents/sota-personas ~/.roo-code/agents/ -r
    # Install specific category
cp agents/core-development ~/.roo-code/agents/ -r

# Install SOTA personas only
cp agents/sota-personas ~/.roo-code/agents/ -r

  8. Convert CLI custom modes to VS Code format

    main

    Use the convert_modes.py script to transform Roo Code custom modes from the CLI-compatible YAML format into the VS Code extension-compatible format. The conversion process uses a 'Smart Merge' strategy: it updates existing modes, adds new ones, and preserves modes that aren't being converted, allowing for incremental updates.

    Conversion Commands

    Convert all modes:

    python3 convert_modes.py convert all

    Convert specific modes (by slug):

    python3 convert_modes.py convert code-skeptic architect python-pro

    Convert to a custom output directory:

    python3 convert_modes.py convert all --output my_custom_modes
    python3 convert_modes.py convert all

  10. Install converted modes into VS Code

    main

    Once modes are converted, you can install them into your Roo Code VS Code extension environment using the copy command. This command automatically detects the correct paths for different platforms.

    Automated Installation

    For Remote Environments (WSL/SSH):

    python3 convert_modes.py copy remote

    For Local Environments:

    python3 convert_modes.py copy local

    Manual Installation

    If the automated command fails, you can manually copy the files to the following locations:

    Remote (WSL/SSH):

    cp converted_modes/custom_modes.yaml ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/settings/
cp -r converted_modes/.roo ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/settings/

    Local Linux:

    cp converted_modes/custom_modes.yaml ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/
cp -r converted_modes/.roo ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/

    Local macOS:

    cp converted_modes/custom_modes.yaml ~/Library/Application\ Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/
cp -r converted_modes/.roo ~/Library/Application\ Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/

    Local Windows (Command Prompt):

    copy converted_modes\custom_modes.yaml %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\
xcopy /E /I converted_modes\.roo %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\.roo
    python3 convert_modes.py copy local

  11. Execute Chaos Engineering & Resilience Verification

    main

    To verify system resilience, follow this structured experiment process:

    1. Define Hypothesis: Establish a steady-state hypothesis and exact success metrics.
    2. Select Failure: Choose one narrow failure (e.g., one pod, one Availability Zone, or one specific dependency).
    3. Inject Failure: Inject the failure during a low-traffic window with full observability enabled.
    4. Measure: Predict behavior $\rightarrow$ run experiment $\rightarrow$ measure deviation $\rightarrow$ restore system.
    5. Document: Record the results in CHAOS.md, including the hypothesis, prediction, actual result, and the resilience gap closed.

  12. Verify and compile custom modes

    main

    Use the provided scripts to ensure your custom modes are valid and to update the active Roo Code configuration.

    Verification

    After modifying each mode, run the verification script. It must output ✅ ALL CHECKS PASSED.

    python3 scripts/verify_modes.py

    Compilation

    After every ~10 modes, regenerate the .roomodes and custom_modes.yaml files using:

    python3 scripts/compile_modes.py

    Testing a single mode in Roo Code

    To test a specific mode without affecting your main configuration:

    1. Generate a single-mode version of the configuration:
      python3 scripts/batch_roomodes.py --single <mode_slug>
    2. Copy the generated file to your active .roomodes:
      cp .roomodes.single-<mode_slug> .roomodes
    3. Reload the VS Code window.
    # Verify all modes
python3 scripts/verify_modes.py

# Compile to .roomodes
python3 scripts/compile_modes.py

# Test a single mode in Roo Code (example for 'debug' slug)
python3 scripts/batch_roomodes.py --single debug
cp .roomodes.single-debug .roomodes