### Project Setup and Dependency Installation

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Clones the repository, sets up a Python virtual environment, and installs project dependencies. This is the initial setup for development.

```bash
git clone git@github.com:jtgsystems/Custom-Modes-Roo-Code.git
cd Custom-Modes-Roo-Code

python3 -m venv venv
source venv/bin/activate

pip install pyyaml
```

--------------------------------

### Verify Installation with Help Commands

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Verifies the installation of project scripts by running their help commands. This confirms that the setup was successful and the scripts are executable.

```bash
python3 scripts/validate_custom_modes.py --help
python3 vs-code/convert_modes.py --help
```

--------------------------------

### Python Development Environment Setup

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Commands to set up a Python virtual environment, activate it, install dependencies, and run validation tests.

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install dependencies
pip install pyyaml

# Run validation tests
python3 scripts/validate_custom_modes.py

# Run conversion with help
python3 vs-code/convert_modes.py --help
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Installs the necessary Python dependencies for the project. Ensure you have activated your virtual environment before running.

```bash
pip install pyyaml
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Install the necessary Python packages for the conversion script. It is recommended to use a virtual environment for managing dependencies.

```bash
# Install required dependencies
pip install pyyaml
```

```bash
# Or using a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install pyyaml
```

--------------------------------

### CLI Custom Modes Format Example

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Example of the custom modes format used in the CLI.

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

--------------------------------

### Manual Installation - Local Linux

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Manually copy converted modes to the VS Code settings directory for local Linux installations.

```bash
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/
```

--------------------------------

### Example: Good Custom Mode YAML

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/AGENT_BRIEF.md

Demonstrates a well-structured custom mode with differentiated and detailed description, roleDefinition, and whenToUse fields.

```yaml
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.
```

--------------------------------

### Conversion Complete Output Example

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Example output indicating the completion of a conversion process. It details the number of updated, added, and kept modes, demonstrating the smart merge behavior.

```text
Conversion complete!
Output directory: 'converted_modes'
Total modes in output: 15
  Updated: 3 mode(s)
  Added: 2 new mode(s)
  Kept: 10 existing mode(s)
```

--------------------------------

### VS Code Custom Modes Format Example

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Example of the custom modes format converted for VS Code.

```yaml
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]
```

--------------------------------

### Manual Installation - Local Windows

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Manually copy converted modes to the VS Code settings directory for local Windows installations.

```cmd
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
```

--------------------------------

### Full Installation of Roo Code Agents

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Clone the repository and copy the agents directory to the .roo-code configuration folder for a full installation.

```bash
git clone https://github.com/jtgsystems/Custom-Modes-Roo-Code.git
cd Custom-Modes-Roo-Code
cp -r agents ~/.roo-code/custom-modes/
```

--------------------------------

### Example: Bad Custom Mode YAML

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/AGENT_BRIEF.md

Illustrates a custom mode with identical and short description and roleDefinition fields, and a generic whenToUse field.

```yaml
description: You debug code.
roleDefinition: You debug code.
whenToUse: Use when you need debug expertise.
```

--------------------------------

### Manual Installation - Local macOS

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Manually copy converted modes to the VS Code settings directory for local macOS installations.

```bash
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/
```

--------------------------------

### Selective Agent Installation

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/README.md

Install specific categories or individual agents by copying their directories into the Roo Code agents folder.

```bash
# Install specific category
cp agents/core-development ~/.roo-code/agents/ -r

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

--------------------------------

### Manual Installation - Remote Environment (WSL/SSH)

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Manually copy converted modes to the VS Code settings directory for remote environments.

```bash
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/
```

--------------------------------

### List Available Modes

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Use this command to display all available custom modes, organized alphabetically. This is useful for getting an overview of all supported modes.

```bash
python3 vs-code/convert_modes.py list
```

--------------------------------

### Full Repository Installation

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/README.md

Clone the entire repository, convert YAML agents to VS Code format using a Python script, and copy them to the Roo Code settings directory.

```bash
# Clone the complete repository
git clone https://github.com/jtgsystems/Custom-Modes-Roo-Code.git
cd Custom-Modes-Roo-Code

# Convert YAML agents to VS Code format
cd vs-code/
python3 convert_modes.py

# Copy converted modes to Roo Code settings
cp -r converted_modes/.roo/ ~/.config/Antigravity/User/globalStorage/rooveterinaryinc.roo-cline/settings/.roo/
```

--------------------------------

### Selective Installation of Roo Code Agents

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Install specific agent categories or individual agents by copying them to the appropriate .roo-code directory.

```bash
# Install specific category
cp -r agents/core-development ~/.roo-code/agents/

# Install specific agent
cp agents/language-specialists/python/python-developer.yaml ~/.roo-code/agents/
```

--------------------------------

### Roo Code Conversion Script Commands

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Provides a quick reference for common commands used with the `convert_modes.py` script. These commands cover listing, searching, converting, and installing modes.

```bash
# Workflow example
python3 convert_modes.py list                    # See all modes
python3 convert_modes.py search *python*         # Find Python modes
python3 convert_modes.py convert python-pro      # Convert one mode
python3 convert_modes.py convert all             # Convert all (merges)
python3 convert_modes.py copy remote             # Install to VS Code
```

--------------------------------

### Install Converted Modes to VS Code

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Copy the converted custom modes directly into your VS Code installation. This command supports both remote and local VS Code environments.

```bash
# Copy to remote VS Code server
python3 vs-code/convert_modes.py copy remote
```

```bash
# Copy to local VS Code installation
python3 vs-code/convert_modes.py copy local
```

--------------------------------

### YAML Agent Configuration with Edit Permissions

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Illustrates how to define specific file editing permissions within the agent configuration's 'groups' section. This example restricts 'edit' access to TypeScript and JavaScript files only.

```yaml
groups:
  - read
  - [edit, {fileRegex: "\\.(ts|js|json)$", description: "TypeScript/JavaScript files only"}]
  - command
```

--------------------------------

### Command-Line Options Help

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Display the help message for the conversion script, outlining available commands, arguments, and options. This is useful for understanding the script's full capabilities.

```bash
Usage: python3 convert_modes.py {list|search|convert|purge|copy} [args...] [options]

Commands:
  list                List all available modes
  search              Search for modes by pattern (supports wildcards)
  convert             Convert modes to VS Code format (merges with existing)
  purge               Empty the output directory
  copy                Copy converted modes to VS Code settings

Arguments:
  For search:         One or more search patterns (supports * wildcard)
  For convert:        Mode slugs to convert (use "all" for all modes)
  For copy:           Destination: 'remote' or 'local'

Options:
  --source PATH       Source custom_modes.yaml file (default: ../custom_modes.yaml)
  --output DIR        Output directory (default: converted_modes)
  --help              Show help message

Examples:
  # List and search
  python3 convert_modes.py list
  python3 convert_modes.py search code* *python*

  # Convert (merges with existing output)
  python3 convert_modes.py convert all
  python3 convert_modes.py convert code-skeptic architect
  python3 convert_modes.py convert python-pro --output my_modes

  # Manage output
  python3 convert_modes.py purge

  # Copy to VS Code
  python3 convert_modes.py copy remote
  python3 convert_modes.py copy local
```

--------------------------------

### Clone Repository and Navigate to Agents

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/README.md

Clone the repository to your local machine and navigate to the agents directory. This is the first step to accessing and using the AI agents.

```bash
git clone https://github.com/jtgsystems/Custom-Modes-Roo-Code.git
cd Custom-Modes-Roo-Code/agents
```

--------------------------------

### Add New Agent Configuration

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Copy the template to create a new agent configuration file in the appropriate category and subcategory.

```bash
cp template.yaml agents/category/subcategory/your-agent.yaml
```

--------------------------------

### List Available Modes

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Use this command to display all available custom modes organized alphabetically. Navigate to the script's directory first.

```bash
cd Custom-Modes-Roo-Code/vs-code
python3 convert_modes.py list
```

--------------------------------

### Fork Repository Command

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CONTRIBUTING.md

Clone the project repository to your local machine to begin development. Replace YOUR-USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR-USERNAME/Custom-Modes-Roo-Code.git
cd Custom-Modes-Roo-Code
```

--------------------------------

### Purge Output Directory

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Empty the output directory, removing all previously converted modes. Use this command to start with a clean slate.

```bash
python3 convert_modes.py purge
```

--------------------------------

### Copy Converted Modes to Remote Environment

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Copy the converted custom modes to a remote environment, such as WSL or an SSH server. This facilitates using the modes in a remote VS Code setup.

```bash
python3 convert_modes.py copy remote
```

--------------------------------

### Agent Development Workflow

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Steps to create a new agent template, edit its configuration, validate it, and test it with Roo Code.

```bash
# Copy template
cp agents/template.yaml agents/category/new-agent.yaml

# Edit agent
nano agents/category/new-agent.yaml

# Validate
python3 scripts/validate_custom_modes.py

# Test with Roo Code
roo-code validate agents/category/new-agent.yaml
```

--------------------------------

### Manage Custom Modes with Python Tooling

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Commands to list, search, convert, purge, and copy custom modes using a Python script. Use --help for more options.

```bash
# List all available modes
python3 vs-code/convert_modes.py list

# Search for specific modes
python3 vs-code/convert_modes.py search python*
python3 vs-code/convert_modes.py search *security* *audit*

# Convert all modes to VS Code format
python3 vs-code/convert_modes.py convert all

# Convert specific modes
python3 vs-code/convert_modes.py convert code-skeptic architect python-developer

# Convert with custom output directory
python3 vs-code/convert_modes.py convert all --output custom_output

# Purge converted modes directory
python3 vs-code/convert_modes.py purge

# Copy to VS Code (remote environment)
python3 vs-code/convert_modes.py copy remote

# Copy to VS Code (local environment)
python3 vs-code/convert_modes.py copy local
```

--------------------------------

### Agent Structure Template

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CONTRIBUTING.md

This YAML template defines the structure for a new agent, including its name, version, category, role, capabilities, frameworks, security features, best practices, and examples.

```yaml
name: "Agent Name"
version: "2025.1"
category: "category-name"
subcategory: "subcategory-name"
description: "Brief one-line description"

role: |
  Detailed multi-line role description.
  Explain what this agent does and when to use it.

capabilities:
  - Capability 1
  - Capability 2
  - Capability 3

frameworks:
  - Framework 1
  - Framework 2

security_features:
  - input_validation
  - secure_coding_practices
  - vulnerability_scanning

best_practices:
  - Practice 1
  - Practice 2

examples:
  - example: "Use case 1"
    command: "roo-code command"
  - example: "Use case 2"
    command: "roo-code command"
```

--------------------------------

### XML Instruction File Generation

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

The `customInstructions` content from CLI format is extracted to this XML file structure.

```text
.roo/rules-code-skeptic/1_instructions.xml
```

--------------------------------

### Manual XML Enhancement Structure

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Illustrates the directory structure before and after manually enhancing XML files for better organization. This approach is recommended for frequently used modes.

```bash
# Before (auto-converted)
rules-code-skeptic/
└── 1_instructions.xml  # All content in one file

# After (manually enhanced)
rules-code-skeptic/
├── 1_workflow.xml       # Structured workflow steps
├── 2_quality_gates.xml  # Quality checklist
├── 3_verification.xml   # Verification procedures
└── 4_examples.xml       # Concrete examples
```

--------------------------------

### Navigate and Pull Repository Changes

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Commands to navigate to the repository directory and update local changes from the main branch.

```bash
# Navigate to repository
cd /tmp/repo-updates/Custom-Modes-Roo-Code

# Update from remote
git pull origin main
```

--------------------------------

### Secure Coding Practices Configuration

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/SECURITY.md

This YAML snippet outlines secure coding best practices that contributors should follow. It includes avoiding `eval()` or `exec()` with user input, sanitizing file paths, using parameterized queries, and implementing proper error handling.

```yaml
best_practices:
  - Never use eval() or exec() with user input
  - Sanitize all file paths
  - Use parameterized queries
  - Implement proper error handling
```

--------------------------------

### Basic Roo Code Agent Usage

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

List available agents, configure the agent path, and activate an agent using the Roo Code CLI.

```bash
# List available agents
ls agents/core-development/general/

# Configure Roo Code
roo-code config set agent-path agents/python-developer.yaml

# Activate agent
roo-code activate python-developer
```

--------------------------------

### Convert Modes to Custom Output Directory

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Convert all custom modes and specify a custom directory for the output files. This is useful for organizing different sets of modes.

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

--------------------------------

### Inspect and Count Agents

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Commands to list agent files and count the number of YAML configuration files for agents.

```bash
# View agent structure
ls -la agents/

# Count agents
find agents -name "*.yaml" | wc -l
```

--------------------------------

### Push to Fork Command

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CONTRIBUTING.md

Push your committed changes to your fork on GitHub. Replace 'feature/new-agent-name' with your branch name.

```bash
git push origin feature/new-agent-name
```

--------------------------------

### Create Feature Branch Command

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CONTRIBUTING.md

Create a new branch for your feature or fix. Use descriptive names for branches, such as 'feature/new-agent-name' or 'fix/issue-description'.

```bash
git checkout -b feature/new-agent-name
# or
git checkout -b fix/issue-description
```

--------------------------------

### List Mode Files

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/AGENT_BRIEF.md

Command to list all YAML files in the custom_modes.d directory, sorted alphabetically, to determine the processing order.

```bash
find custom_modes.d -name "*.yaml" | sort
```

--------------------------------

### Commit Changes Command

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CONTRIBUTING.md

Stage all changes and commit them with a message following the Conventional Commits specification. Use 'feat' for new features or agents.

```bash
git add .
git commit -m "feat: add Python FastAPI expert agent"
```

--------------------------------

### Search for Modes

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/vs-code/README.md

Search for custom modes using wildcard patterns. Multiple patterns can be combined to narrow down the search results.

```bash
# 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*
```

--------------------------------

### Dependency Management Configuration

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/SECURITY.md

This YAML snippet details recommended practices for dependency management to keep dependencies secure. It includes regularly updating dependencies, using scanning tools, pinning versions, and auditing third-party libraries.

```yaml
dependencies:
  - Regularly update all dependencies
  - Use dependency scanning tools
  - Pin dependency versions
  - Audit third-party libraries
```

--------------------------------

### Standard YAML Agent Configuration Structure

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Defines the standard YAML format for agent configurations, including fields for identifier, display name, category, role, instructions, permissions, and versioning. Ensure all fields are correctly populated for agent functionality.

```yaml
slug: agent-identifier          # Unique kebab-case identifier
name: "🔧 Agent Display Name"   # UI display name with optional emoji
category: category-name         # Primary category classification
subcategory: subcategory-name   # Optional subcategory
roleDefinition: |
  Multi-line description of agent responsibilities
customInstructions: |
  Detailed workflow guidelines and best practices
groups:
  - read                        # File reading access
  - edit                        # File editing access
  - browser                     # Web browser access
  - command                     # Command execution
  - mcp                         # MCP server access
version: "2025.1"              # Version compliance
lastUpdated: "2025-09-20"      # Last modification date
```

--------------------------------

### Search Modes with Wildcards

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/CLAUDE.md

Find custom modes using wildcard pattern matching. This command supports single or multiple wildcard patterns for flexible searching.

```bash
python3 vs-code/convert_modes.py search python*
```

```bash
python3 vs-code/convert_modes.py search *architect* *security*
```

--------------------------------

### Compilation Script

Source: https://github.com/jtgsystems/custom-modes-roo-code/blob/main/AGENT_BRIEF.md

Command to run periodically (e.g., every ~10 modes) to regenerate .roomodes and custom_modes.yaml files.

```bash
python3 scripts/compile_modes.py
```