This workflow guides you through creating new custom modes or editing existing ones for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation. .roomodes in the workspace root directory Workspace modes are the default target for project-specific modes and for overrides. VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI) Global modes are used system-wide and are created automatically on Roo Code startup. If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins. Both files use the same YAML schema: a top-level customModes: list of mode objects. Mode definitions are YAML objects within customModes:. Use YAML block scalars (e.g., >-) for multi-line text fields when helpful. If you must embed explicit newlines in a quoted string, use \n for newlines and \n\n for blank lines. groups is required and is a YAML array. It may be empty when a mode should not have access to optional permissions. Each groups entry may be: - a simple string (unrestricted permission group), or - a structured entry that restricts the permission to a subset of files (e.g., fileRegex + description for edit restrictions). slug name roleDefinition groups description whenToUse customInstructions Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/) customModes: - slug: example-mode name: Example Mode description: Short five-word summary roleDefinition: >- You are Roo Code, a [specialist type] who... Key areas: - Area one - Area two whenToUse: >- Use this mode when... groups: - read - - edit - fileRegex: \\.(md|mdx)$ description: Documentation files only customInstructions: >- Optional brief glue text. Identify whether the user wants to create a new mode or edit an existing one User mentions a specific mode by name or slug User references a mode directory path (e.g., .roo/rules-[mode-slug]) User asks to modify, update, enhance, or fix an existing mode User says "edit this mode" or "change this mode" User asks to create a new mode User describes a new responsibility not covered by existing modes User says "make a mode for" or "create a mode that" I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one? Create a new mode for a specific purpose Edit an existing mode to add new responsibilities Fix issues in an existing mode Enhance an existing mode with better workflows When the user asks about a specific mode by name/slug (including phrases like "global mode"), resolve where that mode is defined before doing broad repository searches. Check the workspace override first by reading .roomodes. If not present (or the user explicitly requests global scope), inspect the global custom modes settings file. Note: its exact path is determined by the extension at runtime (do not hardcode a machine-specific path). If the mode is workspace-scoped, read its instruction directory .roo/rules-[mode-slug]/. If the mode entry is found in either .roomodes or the global file, proceed directly to analysis/edits without additional discovery. Understand what the user wants the new mode to accomplish Ask about the mode's primary purpose and use cases Identify what types of tasks the mode should handle Determine what repository access and permissions the mode needs Clarify any special behaviors or restrictions What is the primary purpose of this new mode? What types of tasks should it handle? A mode for writing and maintaining documentation A mode for database schema design and migrations A mode for API endpoint development and testing A mode for performance optimization and profiling Create the mode definition with all required fields Default to workspace-scoped modes unless the user explicitly requests a global mode. User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file. User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository. Unique identifier (lowercase, hyphens allowed) Keep it short and descriptive (e.g., "api-dev", "docs-writer") Display name with optional emoji Use an emoji that represents the mode's purpose Detailed description of the mode's role and expertise Start with "You are Roo Code, a [specialist type]..." List specific areas of expertise Mention key technologies or methodologies Permission groups the mode can access The concrete group names and any nesting structure are runtime-defined and may evolve. Treat these as conceptual categories and map them to the closest available equivalents. File reading and searching File editing (can be restricted by regex) Command execution Browser interaction MCP servers Short human-readable summary (aim ~5 words) Keep it scannable and concrete Clear description for the Orchestrator Explain specific scenarios and task types Prefer keeping substantial mode guidance in XML files within .roo/rules-[mode-slug]/. The underlying mode system supports customInstructions, but large instruction blocks there are easier to duplicate/drift. Use customInstructions only for brief "glue" text when needed. Note: the underlying mode system supports a customInstructions field, but this repository intentionally keeps detailed instructions in .roo/rules-[mode-slug]/ XML files to avoid duplication and drift. Configure appropriate file access permissions Restrict edit access to specific file types groups: - read - - edit - fileRegex: \.(md|txt|rst)$ description: Documentation files only - command Use regex patterns to limit file editing scope Provide clear descriptions for restrictions Consider the principle of least privilege Design structured instruction files in .roo/rules-[mode-slug]/ Main workflow and step-by-step processes Guidelines and conventions Reusable code patterns and examples Decision criteria and guardrails Complete workflow examples Use semantic tag names that describe content Nest tags hierarchically for better organization Include code examples in CDATA sections when needed Add comments to explain complex sections Fully understand the existing mode before making any changes Locate and read the mode configuration in .roomodes When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence Read all XML instruction files in .roo/rules-[mode-slug]/ Analyze the mode's current scope, permissions, and limitations Understand the mode's role in the broader ecosystem What specific aspects of the mode would you like to change or enhance? Adjust permissions or restrictions Fix issues with current workflows or instructions Improve the mode's roleDefinition or whenToUse description Enhance XML instructions for better clarity Understand how proposed changes will affect the mode Compatibility with existing workflows Impact on file permissions and capability access Consistency with mode's core purpose Integration with other modes Role and scope: roleDefinition matches actual scope and permissions; remove scope creep Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes Permissions: groups and fileRegex follow least-privilege and match instructions Instructions hygiene: no contradictions or duplicates across XML files Naming consistency: tag names and terminology are consistent Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes) Boundaries: clear handoffs to other modes; no overlapping responsibilities Search for repeated guidance and conflicting directives across files I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct? Yes, that's exactly what I want to change Mostly correct, but let me clarify some details No, I meant something different I'd like to add additional changes Create a detailed plan for modifying the mode Identify which files need to be modified Determine if new XML instruction files are needed Check for potential conflicts or contradictions Plan the order of changes for minimal disruption Consolidate overlapping instructions into a single source of truth Align with XML best practices (semantic tags, hierarchical nesting) Standardize whenToUse/whenNotToUse language and boundaries Centralize preamble rules and autonomy calibration Tighten fileRegex to least-privilege; add clear descriptions Ensure instructions match configured permissions Split overly long files; ensure 6_error_handling and 7_communication are present or updated Update 5_examples.xml to reflect new workflows and refactors Include before/after diffs where helpful .roomodes: roleDefinition and whenToUse .roo/rules-[slug]/ XML instruction files Examples and quick_reference sections Privately evaluate the planned changes against a 5–7 category rubric before implementation Cohesion across files Permissions and file restrictions (least privilege) Orchestrator fit (whenToUse/whenNotToUse clarity) XML structure and naming consistency Mode boundaries and handoff points Examples and testability Iterate on the plan until it passes the rubric; do not expose the rubric to the user Apply the planned modifications to the mode Update .roomodes configuration if needed Modify existing XML instruction files Create new XML instruction files if required Update examples and documentation Remove duplicate or contradictory instruction blocks across XML files Delete or migrate deprecated fields (e.g., customInstructions in .roomodes) Tighten fileRegex patterns and add clear descriptions Normalize tag names, terminology, and structure Ensure whenToUse/whenNotToUse and handoff rules are explicit Validate file restriction patterns against the intended file sets Confirm permissions match instruction expectations Re-run validation (section 5) and testing (section 6) Scan the repository for legacy references and remove/modernize as needed Ensure all changes are cohesive and don't contradict each other Mode slug follows naming conventions File restrictions align with mode purpose (least privilege) Permissions are appropriate whenToUse clearly differentiates from other modes All XML files follow consistent structure No contradicting instructions between files; contradiction hierarchy and resolutions documented Examples align with stated workflows Instructions match granted permissions and file restrictions Mode integrates well with Orchestrator Clear boundaries with other modes Handoff points are well-defined I've completed the validation checks. Would you like me to review any specific aspect in more detail? Review the file permission patterns Check for workflow contradictions Verify integration with other modes Everything looks good, proceed to testing Verify the mode works as intended Mode appears in the mode list File restrictions work correctly Instructions are clear and actionable Mode integrates well with Orchestrator All examples are accurate and helpful Changes don't break existing functionality (for edits) New behavior works as expected Create mode in .roomodes for project-specific modes Create mode in the global custom modes settings file for system-wide modes (path is environment-specific) Verify the .roo folder structure contains expected rule directories and XML files Validate file regex patterns against the intended file sets (avoid overbroad matches) Find existing mode implementations and patterns to reuse Read all XML files in a mode directory to understand its structure Always validate changes for cohesion and consistency