Complete Guide: How to Set AI Coding Rules for Roo-Cline (Modes/Rules and more)

Roo-Cline is a fork of Cline that introduces mode-based AI specialization—a paradigm shift from single-behavior assistants to context-aware, permission-restricted agents.

Core Innovation: Instead of one AI assistant with broad permissions, Roo-Cline enables multiple specialized modes, each with:

• Distinct roles (Documentation Writer vs. Code Implementer vs. Security Auditor)
• Granular tool permissions (read-only vs. full edit access)
• File-level restrictions (regex-based patterns limiting which files can be modified)
• Custom instructions (mode-specific coding standards and workflows)
• Sticky model assignments (use cheap models for docs, powerful models for complex code)

When to Choose Roo-Cline

Choose Roo-Cline if you:

• Need granular control over AI behavior
• Work on large, complex codebases requiring specialization
• Want cost optimization through model switching
• Require security boundaries (prevent AI from editing critical files)
• Have multiple developers with different permission needs
• Use workflow-based development (TDD, architecture-first, documentation-driven)

Choose Regular Cline if you:

• Prefer simplicity over advanced features
• Work solo on small-to-medium projects
• Want minimal configuration overhead
• Don't need file-level access restrictions

---

2. Understanding Roo-Cline's Architecture

Component Diagram

┌─────────────────────────────────────────────────────────────┐
│                       VS Code Editor                         │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              Roo-Cline Extension                       │  │
│  │                                                         │  │
│  │  ┌─────────────┐      ┌──────────────────────────┐   │  │
│  │  │ Mode Engine │◄─────┤  .roomodes (YAML/JSON)   │   │  │
│  │  └──────┬──────┘      └──────────────────────────┘   │  │
│  │         │                                              │  │
│  │         │ Loads                                        │  │
│  │         ▼                                              │  │
│  │  ┌─────────────────────────────────────────────┐     │  │
│  │  │         Active Mode Instance                 │     │  │
│  │  │  ┌────────────────┐  ┌─────────────────┐   │     │  │
│  │  │  │ Role Definition │  │  Custom Rules   │   │     │  │
│  │  │  └────────────────┘  └─────────────────┘   │     │  │
│  │  │  ┌────────────────┐  ┌─────────────────┐   │     │  │
│  │  │  │ Tool Permissions│  │ File Restrictions│   │     │  │
│  │  │  └────────────────┘  └─────────────────┘   │     │  │
│  │  └─────────────────────────────────────────────┘     │  │
│  │         │                                              │  │
│  │         │ Enforces                                     │  │
│  │         ▼                                              │  │
│  │  ┌─────────────┐      ┌──────────────────────────┐   │  │
│  │  │ LLM Request │─────►│  .roo/rules-{slug}/*.md  │   │  │
│  │  └─────────────┘      └──────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

File System Layout

your-project/
├── .roomodes                          # Mode definitions (YAML/JSON)
│
├── .roo/
│   ├── rules-code/                    # Code mode instructions
│   │   ├── 01-typescript.md
│   │   ├── 02-react.md
│   │   └── 03-testing.md
│   │
│   ├── rules-docs-writer/             # Documentation mode instructions
│   │   └── writing-standards.md
│   │
│   └── rules-security-auditor/        # Security mode instructions
│       ├── audit-checklist.md
│       └── common-vulns.md
│
├── src/                               # Your application code
├── tests/
└── docs/

Global Configuration:

~/.roo/
├── custom_modes.yaml                  # Global mode definitions
└── rules-{mode-slug}/                 # Global mode instructions
    └── *.md

How Modes Work

1. Mode Selection:

User switches to "Code" mode via dropdown
→ Roo loads .roomodes file
→ Finds mode with slug: "code"
→ Reads roleDefinition, customInstructions, groups (tool permissions)

2. Rule Loading:

→ Checks for .roo/rules-code/ directory
→ Loads all .md files alphabetically
→ Combines with customInstructions from .roomodes
→ Injects into system prompt

3. Permission Enforcement:

User asks AI to edit file: src/api/users.ts
→ Mode checks groups: [read, [edit, { fileRegex: "src/.*\\.ts$" }]]
→ Regex matches → Permission granted
→ AI can proceed with edit

User asks AI to edit file: config/secrets.yaml
→ Regex doesn't match → Permission denied
→ AI responds: "I cannot edit this file type in current mode"

---

3. Configuration Files Deep Dive

.roomodes File

Purpose: Define available modes with metadata, permissions, and instructions.

Location Options:

• Project-specific: .roomodes in project root
• Global (all projects): ~/.roo/custom_modes.yaml

Format: YAML (preferred) or JSON

Precedence: Project modes override global modes with same slug.

---

.roo/rules-{mode-slug}/ Directories

Purpose: Store detailed mode-specific instructions as Markdown files.

Naming Convention: Directory name MUST match mode's slug field.

Loading Behavior:

• Files loaded alphabetically (use numeric prefixes: 01-, 02-)
• All content concatenated
• Combined with customInstructions from .roomodes
• Recursive loading (subdirectories included)
• System files excluded (.DS_Store, .swp, etc.)

Example:

.roo/rules-typescript-expert/
├── 01-core-principles.md
├── 02-type-safety.md
├── 03-patterns/
│   ├── error-handling.md
│   └── async-operations.md
└── 04-testing.md

---

Legacy .clinerules Support

Backward Compatibility: Roo-Cline still reads .clinerules (Cline format).

Use Case: Gradual migration from Cline to Roo-Cline.

Recommendation: Convert to .roomodes + mode-specific rules for full feature access.

---

4. The .roomodes File Format

Complete YAML Schema

customModes:
  # Array of mode definitions
  - slug: unique-mode-id                    # Required: lowercase, hyphens, no spaces
    name: Display Name                      # Required: human-readable, can include emojis
    description: Short summary              # Optional: shown in mode selector
    roleDefinition: |                       # Required: AI's identity/expertise
      You are a [role] specializing in [domain].
      Your focus is [primary responsibility].

    whenToUse: |                            # Optional: for Orchestrator mode delegation
      Use this mode when [specific conditions].

    customInstructions: |                   # Optional: additional guidelines
      ## Section 1
      - Guideline A
      - Guideline B

      ## Section 2
      - Guideline C

    groups:                                 # Required: tool permissions array
      - read                                # Simple: string = unrestricted access
      - - edit                              # Tuple: [tool, restrictions]
        - fileRegex: \\.md$                 # YAML: single backslash
          description: Markdown files only
      - browser
      - command

    source: project                         # Required: "project" or "global"

JSON Alternative

{
  "customModes": [{
    "slug": "unique-mode-id",
    "name": "Display Name",
    "description": "Short summary",
    "roleDefinition": "You are a [role] specializing in [domain].",
    "whenToUse": "Use this mode when [conditions].",
    "customInstructions": "## Guidelines\n- Guideline A",
    "groups": [
      "read",
      ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }],
      "browser"
    ],
    "source": "project"
  }]
}

Field Reference

Field	Type	Required	Purpose
slug	string	✅ Yes	Unique identifier (a-z, 0-9, hyphens only)
name	string	✅ Yes	Display name in UI (spaces, emojis allowed)
description	string	⚠️ Recommended	Summary for mode selector
roleDefinition	string	✅ Yes	Prepended to system prompt (AI's identity)
whenToUse	string	⚠️ Optional	Used by Orchestrator for task delegation
customInstructions	string	⚠️ Optional	Appended to system prompt (can be in files instead)
groups	array	✅ Yes	Tool permissions (simple strings or tuples)
source	string	✅ Yes	"project" or "global"

Slug Requirements

Valid slugs:

• ✅ code
• ✅ docs-writer
• ✅ tdd-red-phase
• ✅ security-audit-2024

Invalid slugs:

• ❌ Code Mode (spaces not allowed)
• ❌ docs_writer (underscores not allowed)
• ❌ Docs-Writer (uppercase not allowed)
• ❌ docs.writer (periods not allowed)

Reserved slugs (override built-in modes):

• code
• architect
• ask
• debug
• orchestrator

---

5. Mode-Specific Rules System

Directory Structure Best Practices

Small Projects (< 10 rules per mode):

.roo/rules-code/
└── rules.md                # Single file

Medium Projects (10-30 rules):

.roo/rules-code/
├── 01-core-standards.md
├── 02-typescript.md
├── 03-react.md
└── 04-testing.md

Large Projects (30+ rules):

.roo/rules-code/
├── 01-project-overview.md
├── 02-architecture/
│   ├── layers.md
│   └── patterns.md
├── 03-languages/
│   ├── typescript.md
│   ├── python.md
│   └── sql.md
├── 04-frameworks/
│   ├── react.md
│   └── fastapi.md
└── 05-testing/
    ├── unit.md
    └── integration.md

Rule File Template

# [Category Name]

## Overview
Brief description of what this rule file covers.

## Core Principles
- High-level guideline 1
- High-level guideline 2

## Detailed Patterns

### Pattern 1: [Name]

**When to use**: [Scenario description]

**Implementation**:

typescript
// ✅ CORRECT
[good example]

// ❌ WRONG
[bad example]

**Rationale**: [Why this pattern]

### Pattern 2: [Name]
[Similar structure]

## Common Mistakes

### Mistake 1: [Description]
**Problem**: [What goes wrong]
**Solution**: [How to fix]

## Verification Checklist
- [ ] Check 1
- [ ] Check 2

Effective Rule Writing

DO:

• ✅ Use concrete code examples with ✅/❌ indicators
• ✅ Explain why, not just what
• ✅ Include verification steps
• ✅ Keep individual files under 500 lines
• ✅ Use Markdown formatting (headers, lists, code blocks)

DON'T:

• ❌ Write vague guidelines ("write clean code")
• ❌ Create monolithic single files (split into topics)
• ❌ Duplicate content across multiple files
• ❌ Include sensitive information (secrets, credentials)
• ❌ Use overly complex language (keep it clear)

---

6. Built-In Modes Reference

Code Mode

Default Behavior:

• Tools: read, edit, command
• Purpose: General-purpose coding and refactoring
• Model: Typically most capable (Claude Sonnet, GPT-4o)

Overriding Built-In Code Mode:

customModes:
  - slug: code                          # Same slug = override
    name: 💻 Code (Project Custom)

    roleDefinition: |
      You are a TypeScript expert working on this Next.js project.
      Focus on type safety, Server Components, and tRPC patterns.

    customInstructions: |
      ## Project-Specific Rules
      - Use pnpm (NOT npm)
      - Server Components by default
      - tRPC for all API calls
      - Zod for validation

    groups:
      - read
      - - edit
        - fileRegex: \.(ts|tsx|js|jsx)$
          description: JavaScript/TypeScript files only
      - command

    source: project

Architect Mode

Default Behavior:

• Tools: read, edit (limited to design docs)
• Purpose: System design, architecture decisions, ADRs
• Focus: Planning without implementation

Custom Architect Example:

customModes:
  - slug: architect
    name: 🏛️ System Architect

    roleDefinition: |
      You are a senior software architect.
      Design maintainable, scalable systems.
      Propose 2-3 solutions with trade-off analysis.

    customInstructions: |
      ## Process
      1. Analyze requirements
      2. Propose 2-3 architectural options
      3. Create comparison table (maintainability, scalability, cost)
      4. Generate Mermaid diagram
      5. Write ADR (Architecture Decision Record)

      ## Output Format
      Save to: docs/adr/ADR-[number]-[title].md

    groups:
      - read
      - - edit
        - fileRegex: (docs/adr/.*\.md|.*\.mermaid)$
      - browser

    source: project

Ask Mode

Default Behavior:

• Tools: read, browser
• Purpose: Answering questions, explaining code, research
• Restriction: No file editing

Use Case: Safe exploration without modification risk.

Debug Mode

Default Behavior:

• Tools: read, edit, command
• Purpose: Troubleshooting, fixing bugs, analyzing errors
• Focus: Diagnostic approach

Orchestrator Mode

Default Behavior:

• Tools: All tools, mode delegation
• Purpose: Multi-step task coordination, delegating to specialized modes
• Advanced: Uses whenToUse field from other modes for intelligent delegation

---

7. Creating Custom Modes

Method 1: Using Roo UI (Easiest)

Steps:

1. Open Modes Panel

   • Click Roo icon in VS Code sidebar
   • Click mode dropdown (top of panel)
   • Click ⚙️ (Settings icon)

2. Create New Mode

   • Click + (New Mode button)
   • Fill form:
     • Name: Display name (e.g., "📝 Documentation Writer")
     • Slug: Auto-generated (editable, e.g., "docs-writer")
     • Description: "Specialized mode for technical documentation"
     • Save Location: Project or Global
     • Role Definition: AI's identity
     • Tool Permissions: Check boxes, add file restrictions
     • Custom Instructions: Additional guidelines

3. Configure Permissions

   • Check tool boxes: read, edit, browser, command, mcp
   • For edit tool:
     • Click "Add Restriction"
     • Enter regex: \\.md$
     • Description: "Markdown files only"

4. Save Mode

   • Click "Create Mode"
   • Mode appears in dropdown
   • .roomodes file updated automatically

Method 2: Ask Roo (Conversational)

Process:

You: "Create a new mode called 'Frontend Specialist'. It should only edit 
React component files (*.tsx, *.jsx). Focus on component design, 
performance optimization, and React 19 patterns."

Roo: [Generates YAML configuration]

customModes:
  - slug: frontend-specialist
    name: 🎨 Frontend Specialist
    roleDefinition: |
      You are a React expert specializing in component architecture.
      Focus on React 19 features, Server Components, and performance.
    groups:
      - read
      - - edit
        - fileRegex: \.(tsx|jsx)$
          description: React components only
      - browser
    source: project

[Offers to save to .roomodes]

You: "Yes, save it"

Roo: ✅ Mode created successfully. Switch to it via dropdown.

Method 3: Manual YAML Editing

Global Modes:

1. Open modes panel → "Edit Global Modes"
2. Opens ~/.roo/custom_modes.yaml in editor
3. Add mode YAML manually
4. Save file
5. Reload VS Code window (Cmd/Ctrl + Shift + P → "Reload Window")

Project Modes:

1. Create/edit .roomodes in project root
2. Add mode YAML
3. Save file
4. Reload VS Code window

Mode Creation Template

customModes:
  - slug: [unique-id]
    name: [Emoji] [Display Name]

    description: >
      [One-sentence summary for mode selector UI]

    roleDefinition: |
      You are [role/expertise].
      You specialize in [domain].
      Your primary focus is [responsibility].

    whenToUse: |
      Use this mode when [specific conditions or task types].
      Examples: [list scenarios]

    customInstructions: |
      ## Section 1: [Category]
      - [Guideline A]
      - [Guideline B]

      ## Section 2: [Category]
      - [Guideline C]

      ## Verification
      Before completing:
      - [ ] [Check 1]
      - [ ] [Check 2]

    groups:
      - read
      - - edit
        - fileRegex: [pattern]
          description: [what files]
      - browser    # Optional: if needs web research
      - command    # Optional: if needs CLI execution

    source: project  # or "global"

---

8. Advanced File Restriction Patterns

Regex Syntax Reference

Critical: Escaping Rules

Format	Syntax	Example
YAML	Single backslash \	fileRegex: \\.md$
JSON	Double backslash \\	"fileRegex": "\\\\.md$"

Common Patterns:

# Markdown files
fileRegex: \.(md|mdx|markdown)$

# TypeScript/JavaScript
fileRegex: \.(ts|tsx|js|jsx)$

# React components only
fileRegex: \.(tsx|jsx)$

# Python files (no notebooks)
fileRegex: ^(?!.*\.ipynb$).*\.py$

# API routes (Next.js)
fileRegex: app/api/.*\.(ts|js)$

# Test files only
fileRegex: .*\.(test|spec)\.(ts|tsx|js|jsx)$

# Configuration files
fileRegex: (\.(json|yaml|yml|toml|env)|.*rc|.*\.config\.(js|ts))$

# Exclude node_modules
fileRegex: ^(?!node_modules/).*\.(ts|tsx)$

# Specific directory
fileRegex: ^src/features/.*\.(ts|tsx)$

# Multiple specific files
fileRegex: (package\.json|tsconfig\.json|README\.md)$

Pattern Testing

Test Your Regex:

1. Use online tool: https://regex101.com
2. Select flavor: ECMAScript (JavaScript)
3. Test string: Use file paths from your project
4. Pattern: Your regex (YAML single-backslash version)

Example Test:

Pattern: \.(md|mdx)$

Test Strings:
✅ README.md          → Match
✅ docs/guide.mdx     → Match
❌ markdown.txt       → No match
❌ README.md.backup   → No match

Security Patterns

Prevent Editing Critical Files:

# Code mode: Allow code files, exclude config
customModes:
  - slug: code
    name: 💻 Code
    groups:
      - read
      - - edit
        - fileRegex: ^(?!.*\.env|.*secrets|.*\.key).*\.(ts|tsx|js|jsx)$
          description: Code files (excluding secrets)

Documentation mode: Markdown only, exclude credentials:

customModes:
  - slug: docs-writer
    name: 📝 Documentation Writer
    groups:
      - read
      - - edit
        - fileRegex: ^(?!.*secret|.*password).*\.(md|mdx)$
          description: Markdown (excluding sensitive docs)

Multi-Pattern Combinations

Allow multiple file types:

# Infrastructure mode: YAML, JSON, Terraform
groups:
  - read
  - - edit
    - fileRegex: \.(yaml|yml|json|tf|tfvars)$
      description: Infrastructure config files

Complex directory patterns:

# Frontend mode: React components and styles
groups:
  - read
  - - edit
    - fileRegex: (components/.*\.(tsx|jsx)|styles/.*\.(css|scss))$
      description: Frontend files only

---

9. Tool Permissions Matrix

Available Tools

Tool	Permission Level	Capabilities	Risk Level
read	View	Read any file in workspace	🟢 Low
edit	Modify	Create, update, delete files	🟡 Medium
browser	Web Access	Browse URLs, search web	🟡 Medium
command	Execute	Run shell commands	🔴 High
mcp	Protocol	Access MCP servers	🟡 Medium

Permission Grant Syntax

Simple (Unrestricted):

groups:
  - read      # Can read any file
  - edit      # Can edit any file
  - command   # Can run any command

Restricted (Tuple Format):

groups:
  - read                                # Unrestricted read
  - - edit                              # Tuple: [tool, restrictions]
    - fileRegex: \\.md$                 # Only these files
      description: Markdown files only
  - - command                           # Restricted commands
    - allowedCommands:                  # Whitelist (hypothetical)
        - npm test
        - git status

Note: As of current version, only edit tool supports fileRegex restrictions. Other tools are either granted or denied entirely.

Permission Strategy by Role

Documentation Writer:

groups:
  - read              # Read all for context
  - - edit
    - fileRegex: \.(md|mdx)$
  - browser           # Research while writing
  # NO command (doesn't need CLI)

Code Implementer:

groups:
  - read
  - - edit
    - fileRegex: (src/.*|tests/.*)\.(ts|tsx|js|jsx)$
  - command           # Run tests, linters
  # NO browser (focus on implementation)

Security Auditor:

groups:
  - read              # Analyze everything
  # NO edit (read-only review)
  - command           # Run security scanners
  # NO browser (offline analysis)

System Administrator:

groups:
  - read
  - - edit
    - fileRegex: (\.env\.example|docker-compose\.yml|Makefile)$
  - command           # Deploy, manage services

---

10. Production-Ready Examples

Example 1: Full-Stack TypeScript Project

Project Structure:

my-app/
├── .roomodes
├── .roo/
│   ├── rules-code/
│   ├── rules-docs-writer/
│   └── rules-test-engineer/
├── apps/
│   ├── web/        # Next.js
│   └── api/        # Express
└── packages/
    ├── ui/
    └── database/

.roomodes Configuration:

customModes:
  # General development
  - slug: code
    name: 💻 Code

    roleDefinition: |
      You are a TypeScript full-stack engineer.
      Expertise: Next.js 15, React 19, tRPC, Drizzle ORM.

    groups:
      - read
      - - edit
        - fileRegex: \.(ts|tsx|js|jsx|json)$
          description: JavaScript/TypeScript files
      - command

    source: project

  # Documentation
  - slug: docs-writer
    name: 📝 Documentation Writer

    roleDefinition: |
      You are a technical writer specializing in developer documentation.
      Focus: clarity, examples, proper formatting.

    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
      - browser

    source: project

  # Testing
  - slug: test-engineer
    name: 🧪 Test Engineer

    roleDefinition: |
      You are a QA engineer specializing in comprehensive testing.
      Use Vitest for unit tests, Playwright for E2E.

    groups:
      - read
      - - edit
        - fileRegex: .*\.(test|spec)\.(ts|tsx|js|jsx)$
          description: Test files only
      - command

    source: project

  # Security review
  - slug: security-auditor
    name: 🛡️ Security Auditor

    roleDefinition: |
      You are a security expert conducting code audits.
      Focus: OWASP Top 10, authentication, data validation.

    customInstructions: |
      ## Audit Checklist
      - [ ] No hardcoded secrets
      - [ ] Input validation (Zod)
      - [ ] SQL injection prevention
      - [ ] XSS prevention
      - [ ] CSRF protection
      - [ ] Rate limiting

    groups:
      - read        # Read-only mode
      - command     # Run security scanners

    source: project

.roo/rules-code/01-typescript.md:

# TypeScript Standards

## Type Safety

### Explicit Return Types (Required)

typescript
// ✅ CORRECT
export function calculateTotal(items: Item[]): number {
return items.reduce((sum, item) => sum + item.price, 0);
}

// ❌ WRONG
export function calculateTotal(items: Item[]) {
return items.reduce((sum, item) => sum + item.price, 0);
}

### Avoid `any` Type

typescript
// ✅ Use unknown + type guards
function processData(data: unknown) {
if (typeof data === 'object' && data !== null) {
// Type narrowed
}
}

// ❌ Never use any
function processData(data: any) {
return data.property; // No safety
}

## Error Handling Pattern

### Result Type (Required)

typescript
type Result =
| { success: true; data: T }
| { success: false; error: string };

async function fetchUser(id: string): Promise> {
try {
const user = await db.query.users.findFirst({
where: eq(users.id, id)
});

if (!user) {
  return { success: false, error: 'User not found' };
}

return { success: true, data: user };

} catch (error) {
logger.error('fetchUser failed', { id, error });
return { success: false, error: 'Database error' };
}
}

## Verification Checklist
- [ ] All functions have explicit return types
- [ ] No `any` types without justification comment
- [ ] Error handling with Result<T> pattern
- [ ] Async operations use async/await (not .then())

.roo/rules-test-engineer/testing-standards.md:

# Testing Standards

## AAA Pattern (Required)

typescript
describe('UserService', () => {
it('creates user with valid data', async () => {
// ARRANGE
const userData = { email: '[e-mail]', name: 'Test' };

// ACT
const result = await userService.create(userData);

// ASSERT
expect(result.success).toBe(true);
expect(result.data).toMatchObject(userData);

});
});

## Coverage Requirements
- Unit tests: 80% minimum
- Integration tests: 70% minimum
- E2E tests: Critical paths only

## Commands
- Run tests: `pnpm test`
- Watch mode: `pnpm test:watch`
- Coverage: `pnpm test:coverage`

---

Example 2: Python FastAPI Microservice

.roomodes:

customModes:
  - slug: backend-dev
    name: 🐍 Backend Developer

    roleDefinition: |
      Python expert specializing in FastAPI microservices.
      Focus: async patterns, Pydantic models, clean architecture.

    groups:
      - read
      - - edit
        - fileRegex: .*\.py$
          description: Python files
      - command

    source: project

  - slug: db-specialist
    name: 🗄️ Database Specialist

    roleDefinition: |
      Database expert for PostgreSQL and SQLAlchemy.
      Focus: migrations, query optimization, transactions.

    groups:
      - read
      - - edit
        - fileRegex: (alembic/versions/.*\.py|.*models\.py|.*schemas\.py)$
          description: Database-related files
      - command

    source: project

.roo/rules-backend-dev/python-standards.md:

# Python Standards

## Type Hints (Required)

python

✅ CORRECT

from typing import Optional

async def get_user(user_id: str) -> Optional[User]:
user = await db.users.find_one({"id": user_id})
return User(**user) if user else None

❌ WRONG

async def get_user(user_id):
user = await db.users.find_one({"id": user_id})
return User(**user) if user else None

## Pydantic Models

python
from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
email: EmailStr
name: str = Field(..., min_length=2, max_length=100)
age: int = Field(ge=18, le=120)

class UserResponse(BaseModel):
id: str
email: EmailStr
name: str

class Config:
    from_attributes = True

## Async Best Practices

python

✅ CORRECT: Use async/await

async def fetch_users() -> list[User]:
users = await db.users.find().to_list()
return [User(**u) for u in users]

❌ WRONG: Blocking calls in async

async def fetch_users() -> list[User]:
users = db.users.find().to_list() # Missing await!
return [User(**u) for u in users]

## Error Handling

python
from fastapi import HTTPException

async def get_user(user_id: str) -> User:
user = await db.users.find_one({"id": user_id})

if not user:
    raise HTTPException(
        status_code=404,
        detail=f"User {user_id} not found"
    )

return User(**user)

---

Example 3: TDD Workflow Modes

.roomodes (TDD Three-Phase Approach):

customModes:
  # Phase 1: Red - Write failing tests
  - slug: tdd-red
    name: 🔴 TDD Red Phase

    roleDefinition: |
      TDD specialist for RED phase: writing failing tests.
      Write tests that fail because implementation doesn't exist yet.

    customInstructions: |
      ## Restrictions
      - CANNOT modify production code (only tests)
      - ALL tests must fail (missing implementation)
      - Use descriptive test names

      ## Workflow
      1. Read requirements
      2. Write test for happy path
      3. Write test for error case
      4. Write test for edge case
      5. Verify all fail (not due to setup errors)

    groups:
      - read
      - - edit
        - fileRegex: .*\.(test|spec)\.(ts|tsx|js|jsx|py)$
          description: Test files only
      - command

    source: global

  # Phase 2: Green - Make tests pass
  - slug: tdd-green
    name: 🟢 TDD Green Phase

    roleDefinition: |
      TDD specialist for GREEN phase: minimal implementation.
      Write simplest code to make tests pass.

    customInstructions: |
      ## Restrictions
      - CANNOT modify tests
      - Write minimal code (no over-engineering)
      - Focus on making tests pass

      ## Workflow
      1. Run tests (should fail)
      2. Implement minimal solution
      3. Run tests again (should pass)
      4. If tests still fail, debug and fix

    groups:
      - read
      - - edit
        - fileRegex: ^(?!.*\.(test|spec)\.).*\.(ts|tsx|js|jsx|py)$
          description: Production code only (no tests)
      - command

    source: global

  # Phase 3: Refactor - Improve code
  - slug: tdd-refactor
    name: 🔵 TDD Refactor Phase

    roleDefinition: |
      TDD specialist for REFACTOR phase: improve code quality.
      Refactor without changing behavior (tests remain passing).

    customInstructions: |
      ## Allowed
      - Improve code structure
      - Extract functions/classes
      - Rename variables for clarity
      - Optimize performance

      ## Forbidden
      - Changing test behavior
      - Adding new features
      - Removing functionality

      ## Workflow
      1. Run tests (must pass)
      2. Refactor code
      3. Run tests again (must still pass)
      4. If tests fail, revert changes

    groups:
      - read
      - edit    # Can modify both code and tests
      - command

    source: global

Usage:

# Red phase
Switch to "🔴 TDD Red Phase" mode
→ Write failing tests for new feature

# Green phase
Switch to "🟢 TDD Green Phase" mode
→ Implement minimal code to pass tests

# Refactor phase
Switch to "🔵 TDD Refactor Phase" mode
→ Improve code quality while keeping tests green

---

11. Multi-Project Strategies

Global Mode Library

Use Case: Reuse modes across multiple projects.

Setup:

1. Create global modes:

vim ~/.roo/custom_modes.yaml

1. Add reusable modes:

customModes:
  # Universal documentation mode
  - slug: docs-writer
    name: 📝 Documentation Writer
    roleDefinition: Technical writer for developer documentation
    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
      - browser
    source: global

  # Universal test engineer
  - slug: test-engineer
    name: 🧪 Test Engineer
    roleDefinition: QA specialist for comprehensive testing
    groups:
      - read
      - - edit
        - fileRegex: .*\.(test|spec)\.(ts|tsx|js|jsx|py)$
      - command
    source: global

1. Create global rules:

mkdir -p ~/.roo/rules-docs-writer
vim ~/.roo/rules-docs-writer/standards.md

Per-Project Overrides:

# project-a/.roomodes

customModes:
  # Override global docs-writer for this project
  - slug: docs-writer
    name: 📝 Documentation Writer (Project A)

    roleDefinition: |
      Technical writer for Project A (healthcare domain).
      Must follow HIPAA compliance in all documentation.

    customInstructions: |
      ## Project A Specific
      - Include HIPAA disclaimers
      - No patient data in examples
      - Reference internal compliance guide

    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
      - browser

    source: project    # Project version overrides global

Mode Templates

Concept: Create starter templates for common mode types.

Template Structure:

~/roo-templates/
├── mode-docs-writer.yaml
├── mode-backend-dev.yaml
├── mode-frontend-dev.yaml
└── mode-security-audit.yaml

Example Template (mode-docs-writer.yaml):

customModes:
  - slug: docs-writer
    name: 📝 Documentation Writer

    description: >
      Technical documentation specialist

    roleDefinition: |
      You are a technical writer specializing in developer documentation.
      [CUSTOMIZE: Add domain-specific expertise]

    customInstructions: |
      ## Documentation Standards
      [CUSTOMIZE: Add project-specific guidelines]

      - Clear, concise language
      - Code examples for all concepts
      - Proper Markdown formatting

    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
          description: Markdown files only
      - browser

    source: project

Usage:

# Start new project
cd my-new-project

# Copy template
cp ~/roo-templates/mode-docs-writer.yaml .roomodes

# Customize for project
vim .roomodes

---

12. Import/Export & Team Sharing

Export Mode

Via UI:

1. Open Modes panel
2. Select mode to export
3. Click 📥 Export icon (download button)
4. Choose save location
5. Mode saved as {slug}.yaml

Export Format:

# Exported: 2025-11-29
customModes:
  - slug: frontend-specialist
    name: 🎨 Frontend Specialist
    description: React and Next.js expert
    roleDefinition: |
      [Complete role definition]
    customInstructions: |
      [All instructions]
    groups:
      - read
      - - edit
        - fileRegex: \.(tsx|jsx)$

    # Bundled rule files
    rulesFiles:
      - relativePath: rules-frontend-specialist/react-patterns.md
        content: |
          [Complete file content embedded]
      - relativePath: rules-frontend-specialist/performance.md
        content: |
          [Complete file content embedded]

    source: project

Import Mode

Via UI:

1. Open Modes panel
2. Click 📤 Import icon (upload button)
3. Select YAML file
4. Choose import level:
   • Project: Mode available only in current workspace
   • Global: Mode available in all projects
5. Click "Import"

Result:

• Project import: Creates/updates .roomodes + .roo/rules-{slug}/
• Global import: Updates ~/.roo/custom_modes.yaml + ~/.roo/rules-{slug}/

Team Sharing Workflow

Scenario: Share custom modes with team via Git.

Setup:

1. Create team mode:

# .roomodes (committed to git)
customModes:
  - slug: team-standards
    name: 👥 Team Standards Mode
    roleDefinition: |
      Follows our team's specific coding standards.
    groups:
      - read
      - edit
      - command
    source: project

1. Add team rules:

mkdir -p .roo/rules-team-standards
vim .roo/rules-team-standards/team-conventions.md

1. Commit to repository:

git add .roomodes .roo/
git commit -m "docs: add team standards mode for Roo-Cline"
git push

1. Team members pull:

git pull
# Reload VS Code
# Mode appears in dropdown automatically

Best Practices:

• ✅ Version control .roomodes and .roo/ directories
• ✅ Document mode purposes in README
• ✅ Review mode changes in PRs
• ❌ Don't commit personal modes (use global instead)
• ❌ Don't include sensitive information in rules

---

Mode Distribution Strategies

Strategy 1: Monorepo with Shared Modes

company-monorepo/
├── .roomodes                   # Shared modes for all packages
├── .roo/
│   ├── rules-code/
│   └── rules-docs-writer/
├── packages/
│   ├── frontend/
│   │   └── .roomodes          # Frontend-specific overrides
│   └── backend/
│       └── .roomodes          # Backend-specific overrides

Strategy 2: Separate Modes Repository

# Create company modes repo
git clone [e-mail]:company/roo-modes.git

# Structure
roo-modes/
├── README.md
├── modes/
│   ├── frontend-specialist.yaml
│   ├── backend-specialist.yaml
│   └── security-auditor.yaml
└── install.sh

# Install script
#!/bin/bash
cp modes/*.yaml ~/.roo/custom_modes.yaml
echo "✅ Company modes installed globally"

Strategy 3: npm Package

{
  "name": "@company/roo-modes",
  "version": "1.0.0",
  "files": ["modes/", "install.js"],
  "scripts": {
    "postinstall": "node install.js"
  }
}

# Team members install
npm install -D @company/roo-modes

---

13. Troubleshooting & Optimization

Common Issues

Issue 1: Mode Not Appearing

Symptoms: Created mode doesn't show in dropdown.

Solutions:

1. Validate YAML syntax:

# Check for syntax errors
yamllint .roomodes

1. Check slug validity:
2. Must be lowercase-hyphens-only

3. No spaces, no underscores

4. Check file location:

5. Project: .roomodes (in root)

6. Global: ~/.roo/custom_modes.yaml

7. Reload window:

8. Cmd/Ctrl + Shift + P → "Developer: Reload Window"

Issue 2: Rules Not Loading

Symptoms: AI ignores mode-specific instructions.

Solutions:

1. Verify directory name:
2. Mode slug: frontend-dev

3. Directory: .roo/rules-frontend-dev/ (must match exactly)

4. Check file extensions:

5. Must end in .md (Markdown)

6. Debug mode:

7. Switch to "Debug" mode

8. Ask: "What are your current instructions?"

9. Verify if rules content appears in system prompt

Issue 3: Permission Errors

Symptoms: "I cannot edit this file" or "Permission denied".

Solutions:

1. Check regex pattern:
2. Test regex at regex101.com

3. Remember JSON double-escaping: "\\.md$" vs YAML \.md$

4. Check path matching:

5. Regex matches full relative path from root

6. Use ^ anchor for root matching: ^src/.*

7. Verify tool list:

8. Is edit included in groups?

Optimization Techniques

1. Token Efficiency

Problem: Rules consume context tokens, increasing cost and latency.

Fix: Modularize rules.

Bad:

# One monolithic mode
slug: dev
customInstructions: |
  [Frontend rules]
  [Backend rules]
  [Testing rules]
  [DevOps rules]

Good:

# Specialized modes
slug: frontend
customInstructions: [Frontend rules only]

slug: backend
customInstructions: [Backend rules only]

2. Context Loading

Problem: AI hallucinates non-existent files.

Fix: Use .rooignore or read restrictions.

# .rooignore (like .gitignore)
node_modules/
dist/
coverage/

3. Regex Performance

Problem: Slow file matching.

Fix: Use efficient anchors.

Bad: .*\.ts$ (scans entire string)
Good: \.ts$ (suffix match)

---

14. Migration from Cline

Step-by-Step Migration Guide

Scenario: Converting a project using .clinerules to Roo-Cline modes.

Step 1: Analyze Current Rules

Read .clinerules and identify distinct responsibilities.

# .clinerules (Original)

## Frontend
- React components must use hooks
- Tailwind for styling

## Backend
- Python FastAPI
- Async patterns

## Testing
- Pytest for backend
- Vitest for frontend

Identified Modes:

1. Frontend Developer
2. Backend Developer
3. QA Engineer

Step 2: Create Mode Definitions

Create .roomodes:

customModes:
  - slug: frontend
    name: 🎨 Frontend
    roleDefinition: React/Tailwind specialist
    groups: [read, edit, browser]
    source: project

  - slug: backend
    name: 🐍 Backend
    roleDefinition: Python/FastAPI specialist
    groups: [read, edit, command]
    source: project

  - slug: qa
    name: 🧪 QA Engineer
    roleDefinition: Testing specialist
    groups: [read, edit, command]
    source: project

Step 3: Split Rules

Create directories:

mkdir -p .roo/rules-frontend
mkdir -p .roo/rules-backend
mkdir -p .roo/rules-qa

Frontend Rules (.roo/rules-frontend/standards.md):

# Frontend Standards
- React components must use hooks
- Tailwind for styling

Backend Rules (.roo/rules-backend/standards.md):

# Backend Standards
- Python FastAPI
- Async patterns

QA Rules (.roo/rules-qa/standards.md):

# Testing Standards
- Pytest for backend
- Vitest for frontend

Step 4: Clean Up

# Rename original file to backup
mv .clinerules .clinerules.bak

# Verify modes in VS Code
# Switch to each mode and test

Step 5: Advanced Restrictions (Optional)

Refine permissions:

# Frontend mode regex
fileRegex: \.(tsx|jsx|css)$

# Backend mode regex
fileRegex: \.py$

# QA mode regex
fileRegex: (test|spec)

---

15. Best Practices Compendium

1. Mode Design

• Single Responsibility: Each mode should do one thing well (Unix philosophy).
• Clear Identity: roleDefinition should explicitly state expertise and limitations.
• Descriptive Names: Use emojis and clear labels (🛡️ Security vs Audit).

2. Rule Management

• Versioning: Track rule changes in Git.
• Hierarchy: Use global modes for company standards, project modes for overrides.
• Format: Use Markdown for readability and structure.
• Examples: Always include ✅/❌ code examples.

3. Security

• Least Privilege: Grant minimum necessary permissions.
• Regex Boundaries: Restrict edit access to safe file types.
• Read-Only Audits: Use read-only modes for sensitive reviews.
• No Secrets: Never put API keys or passwords in rules.

4. Workflow Integration

• Task-Based Switching: Switch modes when switching tasks (Coding → Testing → Docs).
• Orchestrator: Use Orchestrator mode to coordinate complex, multi-mode workflows.
• Onboarding: Use modes to guide new team members ("Switch to Onboarding Mode").

5. Maintenance

• Regular Review: Audit modes quarterly.
• Performance Tuning: Split modes if context gets too large.
• Feedback Loop: Update rules when AI makes mistakes.

---

Final Checklist: Production Readiness

Before rolling out Roo-Cline modes to your team:

• [ ] Valid YAML: .roomodes passes yamllint.
• [ ] Regex Safety: File patterns tested and restrictive enough.
• [ ] Rule Clarity: Instructions are unambiguous with examples.
• [ ] Permissions: Tools restricted appropriately (e.g., no shell access for docs mode).
• [ ] Documentation: Mode purposes documented in README.
• [ ] Git Ignore: System files excluded.
• [ ] Fallback: Default Code mode configured as safety net.

---

This guide empowers you to transform Roo-Cline from a coding assistant into a specialized, secure, and highly effective development platform tailored to your exact needs.