Skip to content

Add Mode Writer mode to repo #4600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 14, 2025
Merged

Add Mode Writer mode to repo #4600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4fb27a7
Mode-Writer
hannesrudolph Jun 12, 2025
347ff44
refactor: simplify usage instructions for mode-writer
hannesrudolph Jun 13, 2025
7bebf16
fix: update usage instructions for mode-writer to remove project-spec…
hannesrudolph Jun 13, 2025
5fa5483
fix: update usage instructions for mode-writer to remove project-spec…
hannesrudolph Jun 12, 2025
beba485
Merge branch 'main' into Mode-Writer
hannesrudolph Jun 14, 2025
798eb15
fix: update references to Roo Code in workflow and validation documents
hannesrudolph Jun 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions .roo/rules-mode-writer/1_mode_creation_workflow.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
<mode_creation_workflow>
<overview>
This workflow guides you through creating a new custom mode to be used in the Roo Code Software,
from initial requirements gathering to final implementation.
</overview>

<detailed_steps>
<step number="1">
<title>Gather Requirements</title>
<description>
Understand what the user wants the mode to accomplish
</description>
<actions>
<action>Ask about the mode's primary purpose and use cases</action>
<action>Identify what types of tasks the mode should handle</action>
<action>Determine what tools and file access the mode needs</action>
<action>Clarify any special behaviors or restrictions</action>
</actions>
<example>
<ask_followup_question>
<question>What is the primary purpose of this new mode? What types of tasks should it handle?</question>
<follow_up>
<suggest>A mode for writing and maintaining documentation</suggest>
<suggest>A mode for database schema design and migrations</suggest>
<suggest>A mode for API endpoint development and testing</suggest>
<suggest>A mode for performance optimization and profiling</suggest>
</follow_up>
</ask_followup_question>
</example>
</step>

<step number="2">
<title>Design Mode Configuration</title>
<description>
Create the mode definition with all required fields
</description>
<required_fields>
<field name="slug">
<description>Unique identifier (lowercase, hyphens allowed)</description>
<best_practice>Keep it short and descriptive (e.g., "api-dev", "docs-writer")</best_practice>
</field>
<field name="name">
<description>Display name with optional emoji</description>
<best_practice>Use an emoji that represents the mode's purpose</best_practice>
</field>
<field name="roleDefinition">
<description>Detailed description of the mode's role and expertise</description>
<best_practice>
Start with "You are Roo Code, a [specialist type]..."
List specific areas of expertise
Mention key technologies or methodologies
</best_practice>
</field>
<field name="groups">
<description>Tool groups the mode can access</description>
<options>
<option name="read">File reading and searching tools</option>
<option name="edit">File editing tools (can be restricted by regex)</option>
<option name="command">Command execution tools</option>
<option name="browser">Browser interaction tools</option>
<option name="mcp">MCP server tools</option>
</options>
</field>
</required_fields>
<recommended_fields>
<field name="whenToUse">
<description>Clear description for the Orchestrator</description>
<best_practice>Explain specific scenarios and task types</best_practice>
</field>
</recommended_fields>
<important_note>
Do not include customInstructions in the .roomodes configuration.
All detailed instructions should be placed in XML files within
the .roo/rules-[mode-slug]/ directory instead.
</important_note>
</step>

<step number="3">
<title>Implement File Restrictions</title>
<description>
Configure appropriate file access permissions
</description>
<example>
<comment>Restrict edit access to specific file types</comment>
<code>
groups:
- read
- - edit
- fileRegex: \.(md|txt|rst)$
description: Documentation files only
- command
</code>
</example>
<guidelines>
<guideline>Use regex patterns to limit file editing scope</guideline>
<guideline>Provide clear descriptions for restrictions</guideline>
<guideline>Consider the principle of least privilege</guideline>
</guidelines>
</step>

<step number="4">
<title>Create XML Instruction Files</title>
<description>
Design structured instruction files in .roo/rules-[mode-slug]/
</description>
<file_structure>
<file name="1_workflow.xml">Main workflow and step-by-step processes</file>
<file name="2_best_practices.xml">Guidelines and conventions</file>
<file name="3_common_patterns.xml">Reusable code patterns and examples</file>
<file name="4_tool_usage.xml">Specific tool usage instructions</file>
<file name="5_examples.xml">Complete workflow examples</file>
</file_structure>
<xml_best_practices>
<practice>Use semantic tag names that describe content</practice>
<practice>Nest tags hierarchically for better organization</practice>
<practice>Include code examples in CDATA sections when needed</practice>
<practice>Add comments to explain complex sections</practice>
</xml_best_practices>
</step>

<step number="5">
<title>Test and Refine</title>
<description>
Verify the mode works as intended
</description>
<checklist>
<item>Mode appears in the mode list</item>
<item>File restrictions work correctly</item>
<item>Instructions are clear and actionable</item>
<item>Mode integrates well with Orchestrator</item>
<item>All examples are accurate and helpful</item>
</checklist>
</step>
</detailed_steps>

<quick_reference>
<command>Create mode in .roomodes for project-specific modes</command>
<command>Create mode in global custom_modes.yaml for system-wide modes</command>
<command>Use list_files to verify .roo folder structure</command>
<command>Test file regex patterns with search_files</command>
</quick_reference>
</mode_creation_workflow>
220 changes: 220 additions & 0 deletions .roo/rules-mode-writer/2_xml_structuring_best_practices.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,220 @@
<xml_structuring_best_practices>
<overview>
XML tags help Claude parse prompts more accurately, leading to higher-quality outputs.
This guide covers best practices for structuring mode instructions using XML.
</overview>

<why_use_xml_tags>
<benefit type="clarity">
Clearly separate different parts of your instructions and ensure well-structured content
</benefit>
<benefit type="accuracy">
Reduce errors caused by Claude misinterpreting parts of your instructions
</benefit>
<benefit type="flexibility">
Easily find, add, remove, or modify parts of instructions without rewriting everything
</benefit>
<benefit type="parseability">
Having Claude use XML tags in its output makes it easier to extract specific parts of responses
</benefit>
</why_use_xml_tags>

<core_principles>
<principle name="consistency">
<description>Use the same tag names throughout your instructions</description>
<example>
Always use <step> for workflow steps, not sometimes <action> or <task>
</example>
</principle>

<principle name="semantic_naming">
<description>Tag names should clearly describe their content</description>
<good_examples>
<tag>detailed_steps</tag>
<tag>error_handling</tag>
<tag>validation_rules</tag>
</good_examples>
<bad_examples>
<tag>stuff</tag>
<tag>misc</tag>
<tag>data1</tag>
</bad_examples>
</principle>

<principle name="hierarchical_nesting">
<description>Nest tags to show relationships and structure</description>
<example>
<workflow>
<phase name="preparation">
<step>Gather requirements</step>
<step>Validate inputs</step>
</phase>
<phase name="execution">
<step>Process data</step>
<step>Generate output</step>
</phase>
</workflow>
</example>
</principle>
</core_principles>

<common_tag_patterns>
<pattern name="workflow_structure">
<usage>For step-by-step processes</usage>
<template><![CDATA[
<workflow>
<overview>High-level description</overview>
<prerequisites>
<prerequisite>Required condition 1</prerequisite>
<prerequisite>Required condition 2</prerequisite>
</prerequisites>
<steps>
<step number="1">
<title>Step Title</title>
<description>What this step accomplishes</description>
<actions>
<action>Specific action to take</action>
</actions>
<validation>How to verify success</validation>
</step>
</steps>
</workflow>
]]></template>
</pattern>

<pattern name="examples_structure">
<usage>For providing code examples and demonstrations</usage>
<template><![CDATA[
<examples>
<example name="descriptive_name">
<description>What this example demonstrates</description>
<context>When to use this approach</context>
<code language="typescript">
// Your code example here
</code>
<explanation>
Key points about the implementation
</explanation>
</example>
</examples>
]]></template>
</pattern>

<pattern name="guidelines_structure">
<usage>For rules and best practices</usage>
<template><![CDATA[
<guidelines category="category_name">
<guideline priority="high">
<rule>The specific rule or guideline</rule>
<rationale>Why this is important</rationale>
<exceptions>When this doesn't apply</exceptions>
</guideline>
</guidelines>
]]></template>
</pattern>

<pattern name="tool_usage_structure">
<usage>For documenting how to use specific tools</usage>
<template><![CDATA[
<tool_usage tool="tool_name">
<purpose>What this tool accomplishes</purpose>
<when_to_use>Specific scenarios for this tool</when_to_use>
<syntax>
<command>The exact command format</command>
<parameters>
<parameter name="param1" required="true">
<description>What this parameter does</description>
<type>string|number|boolean</type>
<example>example_value</example>
</parameter>
</parameters>
</syntax>
<examples>
<example scenario="common_use_case">
<code>Actual usage example</code>
<output>Expected output</output>
</example>
</examples>
</tool_usage>
]]></template>
</pattern>
</common_tag_patterns>

<formatting_guidelines>
<guideline name="indentation">
Use consistent indentation (2 or 4 spaces) for nested elements
</guideline>
<guideline name="line_breaks">
Add line breaks between major sections for readability
</guideline>
<guideline name="comments">
Use XML comments <!-- like this --> to explain complex sections
</guideline>
<guideline name="cdata_sections">
Use CDATA for code blocks or content with special characters:
<![CDATA[<code><![CDATA[your code here]]></code>]]>
</guideline>
<guideline name="attributes_vs_elements">
Use attributes for metadata, elements for content:
<example type="good">
<step number="1" priority="high">
<description>The actual step content</description>
</step>
</example>
</guideline>
</formatting_guidelines>

<anti_patterns>
<anti_pattern name="flat_structure">
<description>Avoid completely flat structures without hierarchy</description>
<bad><![CDATA[
<instructions>
<item1>Do this</item1>
<item2>Then this</item2>
<item3>Finally this</item3>
</instructions>
]]></bad>
<good><![CDATA[
<instructions>
<steps>
<step order="1">Do this</step>
<step order="2">Then this</step>
<step order="3">Finally this</step>
</steps>
</instructions>
]]></good>
</anti_pattern>

<anti_pattern name="inconsistent_naming">
<description>Don't mix naming conventions</description>
<bad>
Mixing camelCase, snake_case, and kebab-case in tag names
</bad>
<good>
Pick one convention (preferably snake_case for XML) and stick to it
</good>
</anti_pattern>

<anti_pattern name="overly_generic_tags">
<description>Avoid tags that don't convey meaning</description>
<bad>data, info, stuff, thing, item</bad>
<good>user_input, validation_result, error_message, configuration</good>
</anti_pattern>
</anti_patterns>

<integration_tips>
<tip>
Reference XML content in instructions:
"Using the workflow defined in &lt;workflow&gt; tags..."
</tip>
<tip>
Combine XML structure with other techniques like multishot prompting
</tip>
<tip>
Use XML tags in expected outputs to make parsing easier
</tip>
<tip>
Create reusable XML templates for common patterns
</tip>
</integration_tips>
</xml_structuring_best_practices>
Loading
Loading