Initial commit: The Collective Hub planning documentation
This commit is contained in:
@@ -0,0 +1,491 @@
|
||||
<mode_management_workflow>
|
||||
<overview>
|
||||
This workflow guides you through creating new custom modes or editing existing ones
|
||||
for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation.
|
||||
</overview>
|
||||
|
||||
<mode_scope>
|
||||
<workspace_modes>
|
||||
<location>.roomodes in the workspace root directory</location>
|
||||
<notes>
|
||||
Workspace modes are the default target for project-specific modes and for overrides.
|
||||
</notes>
|
||||
</workspace_modes>
|
||||
|
||||
<global_modes>
|
||||
<location>VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI)</location>
|
||||
<notes>
|
||||
Global modes are used system-wide and are created automatically on Roo Code startup.
|
||||
</notes>
|
||||
</global_modes>
|
||||
|
||||
<precedence>
|
||||
<rule>
|
||||
If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins.
|
||||
</rule>
|
||||
</precedence>
|
||||
|
||||
<schema>
|
||||
<rule>
|
||||
Both files use the same YAML schema: a top-level <code>customModes:</code> list of mode objects.
|
||||
</rule>
|
||||
<format_notes>
|
||||
<note>
|
||||
Mode definitions are YAML objects within <code>customModes:</code>. Use YAML block scalars (e.g., <code>>-</code>) for multi-line text fields when helpful.
|
||||
</note>
|
||||
<note>
|
||||
If you must embed explicit newlines in a quoted string, use <code>\n</code> for newlines and <code>\n\n</code> for blank lines.
|
||||
</note>
|
||||
<note>
|
||||
<code>groups</code> is required and is a YAML array. It may be empty when a mode should not have access to optional permissions.
|
||||
</note>
|
||||
<note>
|
||||
Each <code>groups</code> entry may be:
|
||||
- a simple string (unrestricted permission group), or
|
||||
- a structured entry that restricts the permission to a subset of files (e.g., <code>fileRegex</code> + <code>description</code> for edit restrictions).
|
||||
</note>
|
||||
</format_notes>
|
||||
<required_fields>
|
||||
<field>slug</field>
|
||||
<field>name</field>
|
||||
<field>roleDefinition</field>
|
||||
<field>groups</field>
|
||||
</required_fields>
|
||||
<recommended_fields>
|
||||
<field>description</field>
|
||||
<field>whenToUse</field>
|
||||
</recommended_fields>
|
||||
<optional_fields>
|
||||
<field>customInstructions</field>
|
||||
</optional_fields>
|
||||
<example>
|
||||
<comment>Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/)</comment>
|
||||
<code>
|
||||
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.
|
||||
</code>
|
||||
</example>
|
||||
</schema>
|
||||
</mode_scope>
|
||||
|
||||
<initial_determination>
|
||||
<step number="1">
|
||||
<title>Determine User Intent</title>
|
||||
<description>
|
||||
Identify whether the user wants to create a new mode or edit an existing one
|
||||
</description>
|
||||
<detection_patterns>
|
||||
<pattern type="edit_existing">
|
||||
<indicators>
|
||||
<indicator>User mentions a specific mode by name or slug</indicator>
|
||||
<indicator>User references a mode directory path (e.g., .roo/rules-[mode-slug])</indicator>
|
||||
<indicator>User asks to modify, update, enhance, or fix an existing mode</indicator>
|
||||
<indicator>User says "edit this mode" or "change this mode"</indicator>
|
||||
</indicators>
|
||||
</pattern>
|
||||
<pattern type="create_new">
|
||||
<indicators>
|
||||
<indicator>User asks to create a new mode</indicator>
|
||||
<indicator>User describes a new responsibility not covered by existing modes</indicator>
|
||||
<indicator>User says "make a mode for" or "create a mode that"</indicator>
|
||||
</indicators>
|
||||
</pattern>
|
||||
</detection_patterns>
|
||||
<clarification_question>
|
||||
<ask_user_question>
|
||||
<question>I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one?</question>
|
||||
<follow_up>
|
||||
<suggest>Create a new mode for a specific purpose</suggest>
|
||||
<suggest>Edit an existing mode to add new responsibilities</suggest>
|
||||
<suggest>Fix issues in an existing mode</suggest>
|
||||
<suggest>Enhance an existing mode with better workflows</suggest>
|
||||
</follow_up>
|
||||
</ask_user_question>
|
||||
</clarification_question>
|
||||
</step>
|
||||
|
||||
<step number="2a">
|
||||
<title>Resolve Mode Source (Workspace vs Global)</title>
|
||||
<description>
|
||||
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.
|
||||
</description>
|
||||
<resolution_order>
|
||||
<step>
|
||||
Check the workspace override first by reading <file>.roomodes</file>.
|
||||
</step>
|
||||
<step>
|
||||
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).
|
||||
</step>
|
||||
<step>
|
||||
If the mode is workspace-scoped, read its instruction directory <file>.roo/rules-[mode-slug]/</file>.
|
||||
</step>
|
||||
</resolution_order>
|
||||
<early_stop>
|
||||
If the mode entry is found in either <file>.roomodes</file> or the global file, proceed directly to analysis/edits without additional discovery.
|
||||
</early_stop>
|
||||
</step>
|
||||
</initial_determination>
|
||||
|
||||
<workflow_branches>
|
||||
<branch name="create_new_mode">
|
||||
<step number="3.1">
|
||||
<title>Gather Requirements for New Mode</title>
|
||||
<description>
|
||||
Understand what the user wants the new 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 repository access and permissions the mode needs</action>
|
||||
<action>Clarify any special behaviors or restrictions</action>
|
||||
</actions>
|
||||
<example>
|
||||
<ask_user_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_user_question>
|
||||
</example>
|
||||
</step>
|
||||
|
||||
<step number="3.2">
|
||||
<title>Design Mode Configuration</title>
|
||||
<description>
|
||||
Create the mode definition with all required fields
|
||||
</description>
|
||||
|
||||
<scope_selection>
|
||||
<rule>Default to workspace-scoped modes unless the user explicitly requests a global mode.</rule>
|
||||
<global_mode_trigger>
|
||||
User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file.
|
||||
</global_mode_trigger>
|
||||
<workspace_mode_trigger>
|
||||
User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository.
|
||||
</workspace_mode_trigger>
|
||||
</scope_selection>
|
||||
<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>Permission groups the mode can access</description>
|
||||
<note>
|
||||
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.
|
||||
</note>
|
||||
<options>
|
||||
<option name="read">File reading and searching</option>
|
||||
<option name="edit">File editing (can be restricted by regex)</option>
|
||||
<option name="command">Command execution</option>
|
||||
<option name="browser">Browser interaction</option>
|
||||
<option name="mcp">MCP servers</option>
|
||||
</options>
|
||||
</field>
|
||||
</required_fields>
|
||||
<recommended_fields>
|
||||
<field name="description">
|
||||
<description>Short human-readable summary (aim ~5 words)</description>
|
||||
<best_practice>Keep it scannable and concrete</best_practice>
|
||||
</field>
|
||||
<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>
|
||||
Prefer keeping substantial mode guidance in XML files within <code>.roo/rules-[mode-slug]/</code>.
|
||||
The underlying mode system supports <code>customInstructions</code>, but large instruction blocks there are easier to duplicate/drift.
|
||||
Use <code>customInstructions</code> only for brief "glue" text when needed.
|
||||
|
||||
Note: the underlying mode system supports a <code>customInstructions</code> field,
|
||||
but this repository intentionally keeps detailed instructions in
|
||||
<code>.roo/rules-[mode-slug]/</code> XML files to avoid duplication and drift.
|
||||
</important_note>
|
||||
</step>
|
||||
|
||||
<step number="3.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="3.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_decision_guidance.xml">Decision criteria and guardrails</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>
|
||||
</branch>
|
||||
|
||||
<branch name="edit_existing_mode">
|
||||
<step number="4.1">
|
||||
<title>Immerse in Existing Mode</title>
|
||||
<description>
|
||||
Fully understand the existing mode before making any changes
|
||||
</description>
|
||||
<actions>
|
||||
<action>Locate and read the mode configuration in .roomodes</action>
|
||||
<action>When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence</action>
|
||||
<action>Read all XML instruction files in .roo/rules-[mode-slug]/</action>
|
||||
<action>Analyze the mode's current scope, permissions, and limitations</action>
|
||||
<action>Understand the mode's role in the broader ecosystem</action>
|
||||
</actions>
|
||||
<questions_to_ask>
|
||||
<ask_user_question>
|
||||
<question>What specific aspects of the mode would you like to change or enhance?</question>
|
||||
<follow_up>
|
||||
<suggest>Adjust permissions or restrictions</suggest>
|
||||
<suggest>Fix issues with current workflows or instructions</suggest>
|
||||
<suggest>Improve the mode's roleDefinition or whenToUse description</suggest>
|
||||
<suggest>Enhance XML instructions for better clarity</suggest>
|
||||
</follow_up>
|
||||
</ask_user_question>
|
||||
</questions_to_ask>
|
||||
</step>
|
||||
|
||||
<step number="4.2">
|
||||
<title>Analyze Change Impact</title>
|
||||
<description>
|
||||
Understand how proposed changes will affect the mode
|
||||
</description>
|
||||
<analysis_areas>
|
||||
<area>Compatibility with existing workflows</area>
|
||||
<area>Impact on file permissions and capability access</area>
|
||||
<area>Consistency with mode's core purpose</area>
|
||||
<area>Integration with other modes</area>
|
||||
</analysis_areas>
|
||||
<review_cleanup_checklist>
|
||||
<item>Role and scope: roleDefinition matches actual scope and permissions; remove scope creep</item>
|
||||
<item>Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes</item>
|
||||
<item>Permissions: groups and fileRegex follow least-privilege and match instructions</item>
|
||||
<item>Instructions hygiene: no contradictions or duplicates across XML files</item>
|
||||
<item>Naming consistency: tag names and terminology are consistent</item>
|
||||
<item>Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes)</item>
|
||||
<item>Boundaries: clear handoffs to other modes; no overlapping responsibilities</item>
|
||||
</review_cleanup_checklist>
|
||||
<duplication_and_contradiction_scan>
|
||||
<approach>Search for repeated guidance and conflicting directives across files</approach>
|
||||
</duplication_and_contradiction_scan>
|
||||
<validation_questions>
|
||||
<ask_user_question>
|
||||
<question>I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct?</question>
|
||||
<follow_up>
|
||||
<suggest>Yes, that's exactly what I want to change</suggest>
|
||||
<suggest>Mostly correct, but let me clarify some details</suggest>
|
||||
<suggest>No, I meant something different</suggest>
|
||||
<suggest>I'd like to add additional changes</suggest>
|
||||
</follow_up>
|
||||
</ask_user_question>
|
||||
</validation_questions>
|
||||
</step>
|
||||
|
||||
<step number="4.3">
|
||||
<title>Plan Modifications</title>
|
||||
<description>
|
||||
Create a detailed plan for modifying the mode
|
||||
</description>
|
||||
<planning_steps>
|
||||
<step>Identify which files need to be modified</step>
|
||||
<step>Determine if new XML instruction files are needed</step>
|
||||
<step>Check for potential conflicts or contradictions</step>
|
||||
<step>Plan the order of changes for minimal disruption</step>
|
||||
</planning_steps>
|
||||
<refactor_strategy>
|
||||
<normalize>
|
||||
<rule>Consolidate overlapping instructions into a single source of truth</rule>
|
||||
<rule>Align with XML best practices (semantic tags, hierarchical nesting)</rule>
|
||||
<rule>Standardize whenToUse/whenNotToUse language and boundaries</rule>
|
||||
<rule>Centralize preamble rules and autonomy calibration</rule>
|
||||
</normalize>
|
||||
<permissions>
|
||||
<rule>Tighten fileRegex to least-privilege; add clear descriptions</rule>
|
||||
<rule>Ensure instructions match configured permissions</rule>
|
||||
</permissions>
|
||||
<structure>
|
||||
<rule>Split overly long files; ensure 6_error_handling and 7_communication are present or updated</rule>
|
||||
</structure>
|
||||
<examples_and_tests>
|
||||
<rule>Update 5_examples.xml to reflect new workflows and refactors</rule>
|
||||
<rule>Include before/after diffs where helpful</rule>
|
||||
</examples_and_tests>
|
||||
</refactor_strategy>
|
||||
<artifacts_to_update>
|
||||
<item>.roomodes: roleDefinition and whenToUse</item>
|
||||
<item>.roo/rules-[slug]/ XML instruction files</item>
|
||||
<item>Examples and quick_reference sections</item>
|
||||
</artifacts_to_update>
|
||||
</step>
|
||||
|
||||
<step number="4.4">
|
||||
<title>Silent Self-Reflection Rubric</title>
|
||||
<description>Privately evaluate the planned changes against a 5–7 category rubric before implementation</description>
|
||||
<rubric>
|
||||
<category>Cohesion across files</category>
|
||||
<category>Permissions and file restrictions (least privilege)</category>
|
||||
<category>Orchestrator fit (whenToUse/whenNotToUse clarity)</category>
|
||||
<category>XML structure and naming consistency</category>
|
||||
<category>Mode boundaries and handoff points</category>
|
||||
<category>Examples and testability</category>
|
||||
</rubric>
|
||||
<instruction>Iterate on the plan until it passes the rubric; do not expose the rubric to the user</instruction>
|
||||
</step>
|
||||
|
||||
<step number="4.5">
|
||||
<title>Implement Changes</title>
|
||||
<description>
|
||||
Apply the planned modifications to the mode
|
||||
</description>
|
||||
<implementation_order>
|
||||
<change>Update .roomodes configuration if needed</change>
|
||||
<change>Modify existing XML instruction files</change>
|
||||
<change>Create new XML instruction files if required</change>
|
||||
<change>Update examples and documentation</change>
|
||||
</implementation_order>
|
||||
<cleanup_tasks>
|
||||
<task>Remove duplicate or contradictory instruction blocks across XML files</task>
|
||||
<task>Delete or migrate deprecated fields (e.g., customInstructions in .roomodes)</task>
|
||||
<task>Tighten fileRegex patterns and add clear descriptions</task>
|
||||
<task>Normalize tag names, terminology, and structure</task>
|
||||
<task>Ensure whenToUse/whenNotToUse and handoff rules are explicit</task>
|
||||
</cleanup_tasks>
|
||||
<verification_steps>
|
||||
<step>Validate file restriction patterns against the intended file sets</step>
|
||||
<step>Confirm permissions match instruction expectations</step>
|
||||
<step>Re-run validation (section 5) and testing (section 6)</step>
|
||||
<step>Scan the repository for legacy references and remove/modernize as needed</step>
|
||||
</verification_steps>
|
||||
</step>
|
||||
</branch>
|
||||
</workflow_branches>
|
||||
|
||||
<validation_and_cohesion>
|
||||
<step number="5">
|
||||
<title>Validate Cohesion and Consistency</title>
|
||||
<description>
|
||||
Ensure all changes are cohesive and don't contradict each other
|
||||
</description>
|
||||
<validation_checks>
|
||||
<check type="configuration">
|
||||
<item>Mode slug follows naming conventions</item>
|
||||
<item>File restrictions align with mode purpose (least privilege)</item>
|
||||
<item>Permissions are appropriate</item>
|
||||
<item>whenToUse clearly differentiates from other modes</item>
|
||||
</check>
|
||||
<check type="instructions">
|
||||
<item>All XML files follow consistent structure</item>
|
||||
<item>No contradicting instructions between files; contradiction hierarchy and resolutions documented</item>
|
||||
<item>Examples align with stated workflows</item>
|
||||
<item>Instructions match granted permissions and file restrictions</item>
|
||||
</check>
|
||||
<check type="integration">
|
||||
<item>Mode integrates well with Orchestrator</item>
|
||||
<item>Clear boundaries with other modes</item>
|
||||
<item>Handoff points are well-defined</item>
|
||||
</check>
|
||||
</validation_checks>
|
||||
<cohesion_questions>
|
||||
<ask_user_question>
|
||||
<question>I've completed the validation checks. Would you like me to review any specific aspect in more detail?</question>
|
||||
<follow_up>
|
||||
<suggest>Review the file permission patterns</suggest>
|
||||
<suggest>Check for workflow contradictions</suggest>
|
||||
<suggest>Verify integration with other modes</suggest>
|
||||
<suggest>Everything looks good, proceed to testing</suggest>
|
||||
</follow_up>
|
||||
</ask_user_question>
|
||||
</cohesion_questions>
|
||||
</step>
|
||||
|
||||
<step number="6">
|
||||
<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>
|
||||
<item>Changes don't break existing functionality (for edits)</item>
|
||||
<item>New behavior works as expected</item>
|
||||
</checklist>
|
||||
</step>
|
||||
</validation_and_cohesion>
|
||||
|
||||
<quick_reference>
|
||||
<action>Create mode in .roomodes for project-specific modes</action>
|
||||
<action>Create mode in the global custom modes settings file for system-wide modes (path is environment-specific)</action>
|
||||
<action>Verify the .roo folder structure contains expected rule directories and XML files</action>
|
||||
<action>Validate file regex patterns against the intended file sets (avoid overbroad matches)</action>
|
||||
<action>Find existing mode implementations and patterns to reuse</action>
|
||||
<action>Read all XML files in a mode directory to understand its structure</action>
|
||||
<action>Always validate changes for cohesion and consistency</action>
|
||||
</quick_reference>
|
||||
</mode_management_workflow>
|
||||
@@ -0,0 +1,240 @@
|
||||
<xml_structuring_best_practices>
|
||||
<overview>
|
||||
XML tags help LLMs 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 the model 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 the model 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>
|
||||
<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>
|
||||
<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>
|
||||
<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="decision_guidance_structure">
|
||||
<usage>For documenting decision criteria and guardrails</usage>
|
||||
<template>
|
||||
<decision_guidance>
|
||||
<principles>
|
||||
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||
</principles>
|
||||
|
||||
<constraints>
|
||||
Constraints and guardrails (e.g., permissions, file restrictions, or other limits).
|
||||
</constraints>
|
||||
|
||||
<validation>
|
||||
What to verify after changes (cohesion, examples updated, boundaries clear).
|
||||
</validation>
|
||||
</decision_guidance>
|
||||
</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:
|
||||
<code>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>
|
||||
<guideline name="verbosity">
|
||||
Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested.
|
||||
</guideline>
|
||||
</formatting_guidelines>
|
||||
|
||||
<anti_patterns>
|
||||
<anti_pattern name="flat_structure">
|
||||
<description>Avoid completely flat structures without hierarchy</description>
|
||||
<bad>
|
||||
<instructions>
|
||||
|
||||
<item1>Do this</item1>
|
||||
|
||||
<item2>Then this</item2>
|
||||
|
||||
<item3>Finally this</item3>
|
||||
|
||||
</instructions>
|
||||
</bad>
|
||||
<good>
|
||||
<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_pattern name="over_clarifying_questions">
|
||||
<description>Avoid asking the user to confirm obvious next steps on straightforward tasks</description>
|
||||
<bad>Asking multiple clarifying questions before acting when the task is simple</bad>
|
||||
<good>Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="excessive_searching">
|
||||
<description>Avoid repetitive or redundant searches when the relevant target is already identified</description>
|
||||
<bad>Running multiple identical searches instead of acting</bad>
|
||||
<good>Stop once the change is clearly identified; then implement</good>
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="over_specifying_runtime_behavior">
|
||||
<description>Avoid duplicating runtime behavior that is already defined elsewhere</description>
|
||||
<bad>Documenting execution constraints, operation ordering, or invocation details</bad>
|
||||
<good>Focus on intent, artifacts, decision criteria, and validation expectations</good>
|
||||
</anti_pattern>
|
||||
</anti_patterns>
|
||||
|
||||
<integration_tips>
|
||||
<tip>
|
||||
Reference XML content in instructions:
|
||||
"Using the workflow defined in <workflow> 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>
|
||||
@@ -0,0 +1,307 @@
|
||||
<mode_configuration_patterns>
|
||||
<overview>
|
||||
Common patterns and templates for creating different types of modes, with examples from existing modes in the Roo-Code software.
|
||||
</overview>
|
||||
|
||||
<mode_types>
|
||||
<type name="specialist_mode">
|
||||
<description>
|
||||
Modes focused on specific technical domains or tasks
|
||||
</description>
|
||||
<characteristics>
|
||||
<characteristic>Deep expertise in a particular area</characteristic>
|
||||
<characteristic>Restricted file access based on domain</characteristic>
|
||||
<characteristic>Specialized workflows and decision criteria</characteristic>
|
||||
</characteristics>
|
||||
<example_template>
|
||||
- slug: api-specialist
|
||||
name: 🔌 API Specialist
|
||||
roleDefinition: >-
|
||||
You are Roo Code, an API development specialist with expertise in:
|
||||
- RESTful API design and implementation
|
||||
- GraphQL schema design
|
||||
- API documentation with OpenAPI/Swagger
|
||||
- Authentication and authorization patterns
|
||||
- Rate limiting and caching strategies
|
||||
- API versioning and deprecation
|
||||
|
||||
You ensure APIs are:
|
||||
- Well-documented and discoverable
|
||||
- Following REST principles or GraphQL best practices
|
||||
- Secure and performant
|
||||
- Properly versioned and maintainable
|
||||
whenToUse: >-
|
||||
Use this mode when designing, implementing, or refactoring APIs.
|
||||
This includes creating new endpoints, updating API documentation,
|
||||
implementing authentication, or optimizing API performance.
|
||||
groups:
|
||||
- read
|
||||
- - edit
|
||||
- fileRegex: (api/.*\.(ts|js)|.*\.openapi\.yaml|.*\.graphql|docs/api/.*)$
|
||||
description: API implementation files, OpenAPI specs, and API documentation
|
||||
- command
|
||||
- mcp
|
||||
</example_template>
|
||||
</type>
|
||||
|
||||
<type name="workflow_mode">
|
||||
<description>
|
||||
Modes that guide users through multi-step processes
|
||||
</description>
|
||||
<characteristics>
|
||||
<characteristic>Step-by-step workflow guidance</characteristic>
|
||||
<characteristic>Heavy use of focused clarifying questions</characteristic>
|
||||
<characteristic>Process validation at each step</characteristic>
|
||||
</characteristics>
|
||||
<example_template>
|
||||
- slug: migration-guide
|
||||
name: 🔄 Migration Guide
|
||||
roleDefinition: >-
|
||||
You are Roo Code, a migration specialist who guides users through
|
||||
complex migration processes:
|
||||
- Database schema migrations
|
||||
- Framework version upgrades
|
||||
- API version migrations
|
||||
- Dependency updates
|
||||
- Breaking change resolutions
|
||||
|
||||
You provide:
|
||||
- Step-by-step migration plans
|
||||
- Automated migration scripts
|
||||
- Rollback strategies
|
||||
- Testing approaches for migrations
|
||||
whenToUse: >-
|
||||
Use this mode when performing any kind of migration or upgrade.
|
||||
This mode will analyze the current state, plan the migration,
|
||||
and guide you through each step with validation.
|
||||
groups:
|
||||
- read
|
||||
- edit
|
||||
- command
|
||||
</example_template>
|
||||
</type>
|
||||
|
||||
<type name="analysis_mode">
|
||||
<description>
|
||||
Modes focused on code analysis and reporting
|
||||
</description>
|
||||
<characteristics>
|
||||
<characteristic>Read-heavy operations</characteristic>
|
||||
<characteristic>Limited or no edit permissions</characteristic>
|
||||
<characteristic>Comprehensive reporting outputs</characteristic>
|
||||
</characteristics>
|
||||
<example_template>
|
||||
- slug: security-auditor
|
||||
name: 🔒 Security Auditor
|
||||
roleDefinition: >-
|
||||
You are Roo Code, a security analysis specialist focused on:
|
||||
- Identifying security vulnerabilities
|
||||
- Analyzing authentication and authorization
|
||||
- Reviewing data validation and sanitization
|
||||
- Checking for common security anti-patterns
|
||||
- Evaluating dependency vulnerabilities
|
||||
- Assessing API security
|
||||
|
||||
You provide detailed security reports with:
|
||||
- Vulnerability severity ratings
|
||||
- Specific remediation steps
|
||||
- Security best practice recommendations
|
||||
whenToUse: >-
|
||||
Use this mode to perform security audits on codebases.
|
||||
This mode will analyze code for vulnerabilities, check
|
||||
dependencies, and provide actionable security recommendations.
|
||||
groups:
|
||||
- read
|
||||
- command
|
||||
- - edit
|
||||
- fileRegex: (SECURITY\.md|\.github/security/.*|docs/security/.*)$
|
||||
description: Security documentation files only
|
||||
</example_template>
|
||||
</type>
|
||||
|
||||
<type name="creative_mode">
|
||||
<description>
|
||||
Modes for generating new content or features
|
||||
</description>
|
||||
<characteristics>
|
||||
<characteristic>Broad file creation permissions</characteristic>
|
||||
<characteristic>Template and boilerplate generation</characteristic>
|
||||
<characteristic>Interactive design process</characteristic>
|
||||
</characteristics>
|
||||
<example_template>
|
||||
- slug: component-designer
|
||||
name: 🎨 Component Designer
|
||||
roleDefinition: >-
|
||||
You are Roo Code, a UI component design specialist who creates:
|
||||
- Reusable React/Vue/Angular components
|
||||
- Component documentation and examples
|
||||
- Storybook stories
|
||||
- Unit tests for components
|
||||
- Accessibility-compliant interfaces
|
||||
|
||||
You follow design system principles and ensure components are:
|
||||
- Highly reusable and composable
|
||||
- Well-documented with examples
|
||||
- Fully tested
|
||||
- Accessible (WCAG compliant)
|
||||
- Performance optimized
|
||||
whenToUse: >-
|
||||
Use this mode when creating new UI components or refactoring
|
||||
existing ones. This mode helps design component APIs, implement
|
||||
the components, and create comprehensive documentation.
|
||||
groups:
|
||||
- read
|
||||
- - edit
|
||||
- fileRegex: (components/.*|stories/.*|__tests__/.*\.test\.(tsx?|jsx?))$
|
||||
description: Component files, stories, and component tests
|
||||
- browser
|
||||
- command
|
||||
</example_template>
|
||||
</type>
|
||||
</mode_types>
|
||||
|
||||
<autonomy_configuration>
|
||||
<overview>Configuration patterns to keep modes focused, cohesive, and clearly scoped</overview>
|
||||
<defaults>
|
||||
<cohesion>Prefer a single source of truth for each rule; avoid duplicated instructions</cohesion>
|
||||
<scope>Prefer least privilege; keep file restrictions aligned with purpose</scope>
|
||||
<clarity>Define acceptance criteria and validation gates for typical tasks</clarity>
|
||||
<handoffs>Define explicit boundaries and handoff points to other modes</handoffs>
|
||||
<verbosity>Keep narrative brief; reserve detail for structured outputs and diffs</verbosity>
|
||||
</defaults>
|
||||
<per_mode_guidance>
|
||||
<mode type="specialist_mode">
|
||||
<notes>Tight scope, least privilege, clear boundaries; prefer small targeted changes</notes>
|
||||
</mode>
|
||||
<mode type="workflow_mode">
|
||||
<notes>Step-by-step process with validation gates; ask clarifying questions only when necessary</notes>
|
||||
</mode>
|
||||
<mode type="analysis_mode">
|
||||
<notes>Read-heavy; edits typically constrained to reporting or documentation outputs</notes>
|
||||
</mode>
|
||||
<mode type="creative_mode">
|
||||
<notes>Broader creation scope; ensure examples and tests are included when applicable</notes>
|
||||
</mode>
|
||||
</per_mode_guidance>
|
||||
</autonomy_configuration>
|
||||
|
||||
<permission_patterns>
|
||||
<pattern name="documentation_only">
|
||||
<description>For modes that only work with documentation</description>
|
||||
<configuration>
|
||||
groups:
|
||||
- read
|
||||
- - edit
|
||||
- fileRegex: \.(md|mdx|rst|txt)$
|
||||
description: Documentation files only
|
||||
</configuration>
|
||||
</pattern>
|
||||
|
||||
<pattern name="test_focused">
|
||||
<description>For modes that work with test files</description>
|
||||
<configuration>
|
||||
groups:
|
||||
- read
|
||||
- command
|
||||
- - edit
|
||||
- fileRegex: (__tests__/.*|__mocks__/.*|.*\.test\.(ts|tsx|js|jsx)$|.*\.spec\.(ts|tsx|js|jsx)$)
|
||||
description: Test files and mocks
|
||||
</configuration>
|
||||
</pattern>
|
||||
|
||||
<pattern name="config_management">
|
||||
<description>For modes that manage configuration</description>
|
||||
<configuration>
|
||||
groups:
|
||||
- read
|
||||
- - edit
|
||||
- fileRegex: (.*\.config\.(js|ts|json)|.*rc\.json|.*\.yaml|.*\.yml|\.env\.example)$
|
||||
description: Configuration files (not .env)
|
||||
</configuration>
|
||||
</pattern>
|
||||
|
||||
<pattern name="full_stack">
|
||||
<description>For modes that need broad access</description>
|
||||
<configuration>
|
||||
groups:
|
||||
- read
|
||||
- edit # No restrictions
|
||||
- command
|
||||
- browser
|
||||
- mcp
|
||||
</configuration>
|
||||
</pattern>
|
||||
</permission_patterns>
|
||||
|
||||
<naming_conventions>
|
||||
<convention category="slug">
|
||||
<rule>Use lowercase with hyphens</rule>
|
||||
<good>api-dev, test-writer, docs-manager</good>
|
||||
<bad>apiDev, test_writer, DocsManager</bad>
|
||||
</convention>
|
||||
|
||||
<convention category="name">
|
||||
<rule>Use title case with descriptive emoji</rule>
|
||||
<good>🔧 API Developer, 📝 Documentation Writer</good>
|
||||
<bad>api developer, DOCUMENTATION WRITER</bad>
|
||||
</convention>
|
||||
|
||||
<convention category="emoji_selection">
|
||||
<common_emojis>
|
||||
<emoji meaning="testing">🧪</emoji>
|
||||
<emoji meaning="documentation">📝</emoji>
|
||||
<emoji meaning="design">🎨</emoji>
|
||||
<emoji meaning="debugging">🪲</emoji>
|
||||
<emoji meaning="building">🏗️</emoji>
|
||||
<emoji meaning="security">🔒</emoji>
|
||||
<emoji meaning="api">🔌</emoji>
|
||||
<emoji meaning="database">🗄️</emoji>
|
||||
<emoji meaning="performance">⚡</emoji>
|
||||
<emoji meaning="configuration">⚙️</emoji>
|
||||
</common_emojis>
|
||||
</convention>
|
||||
</naming_conventions>
|
||||
|
||||
<integration_guidelines>
|
||||
<guideline name="orchestrator_compatibility">
|
||||
<description>Ensure whenToUse/whenNotToUse are clear for Orchestrator mode</description>
|
||||
<checklist>
|
||||
<item>Specify concrete task types the mode handles</item>
|
||||
<item>Include trigger keywords or phrases</item>
|
||||
<item>Differentiate from similar modes</item>
|
||||
<item>Mention specific file types or areas</item>
|
||||
<item>Define whenNotToUse with negative triggers and explicit handoffs</item>
|
||||
<item>State stop/ask/handoff rules</item>
|
||||
<item>State default verbosity policy (low narrative; verbose diffs)</item>
|
||||
</checklist>
|
||||
</guideline>
|
||||
|
||||
<guideline name="stop_and_handoff_rules">
|
||||
<description>Define explicit stop conditions, confirmation thresholds, and handoff/ask triggers</description>
|
||||
<checklist>
|
||||
<item>Done-ness: acceptance criteria and validation gates are defined</item>
|
||||
<item>Handoff rules to other modes or “ask a clarifying question” conditions are explicit</item>
|
||||
<item>Boundaries, risks, and validation gates are documented</item>
|
||||
</checklist>
|
||||
</guideline>
|
||||
|
||||
<guideline name="verbosity_policy">
|
||||
<description>Set verbosity defaults to keep narrative short and code edits clear</description>
|
||||
<checklist>
|
||||
<item>Low narrative verbosity in status/progress text</item>
|
||||
<item>High detail only inside code/diffs and structured outputs</item>
|
||||
<item>Code clarity over cleverness; avoid code-golf and cryptic names</item>
|
||||
</checklist>
|
||||
</guideline>
|
||||
|
||||
<guideline name="mode_boundaries">
|
||||
<description>Define clear boundaries between modes</description>
|
||||
<checklist>
|
||||
<item>Avoid overlapping responsibilities</item>
|
||||
<item>Make handoff points explicit</item>
|
||||
<item>Switch modes when appropriate (mechanism varies)</item>
|
||||
<item>Document mode interactions</item>
|
||||
</checklist>
|
||||
</guideline>
|
||||
</integration_guidelines>
|
||||
</mode_configuration_patterns>
|
||||
@@ -0,0 +1,293 @@
|
||||
<instruction_file_templates>
|
||||
<overview>
|
||||
Templates and examples for creating XML instruction files that provide
|
||||
detailed guidance for each mode's behavior and workflows.
|
||||
|
||||
Requirements:
|
||||
- Do not reference runtime implementation details (function names, command names, UI entry points, or execution syntax).
|
||||
- Do not duplicate operational policies that are already defined by the runtime/system prompt.
|
||||
- Focus on workflow intent, required artifacts, decision criteria, and validation expectations.
|
||||
</overview>
|
||||
|
||||
<file_organization>
|
||||
<principle>Number files to indicate execution order</principle>
|
||||
<principle>Use descriptive names that indicate content</principle>
|
||||
<principle>Keep related instructions together</principle>
|
||||
<standard_structure>
|
||||
<file>1_workflow.xml - Main workflow and processes</file>
|
||||
<file>2_best_practices.xml - Guidelines and conventions</file>
|
||||
<file>3_common_patterns.xml - Reusable code patterns</file>
|
||||
<file>4_decision_guidance.xml - Decision criteria and guardrails</file>
|
||||
<file>5_examples.xml - Complete workflow examples</file>
|
||||
<file>6_error_handling.xml - Error scenarios and recovery</file>
|
||||
<file>7_communication.xml - User interaction guidelines</file>
|
||||
</standard_structure>
|
||||
</file_organization>
|
||||
|
||||
<workflow_file_template>
|
||||
<description>Template for main workflow files (1_workflow.xml)</description>
|
||||
<template>
|
||||
<workflow_instructions>
|
||||
<mode_overview>
|
||||
Brief description of what this mode does and its primary purpose
|
||||
</mode_overview>
|
||||
|
||||
<initialization_steps>
|
||||
<step number="1">
|
||||
<action>Understand the user's request</action>
|
||||
<details>
|
||||
Parse the user's input to identify:
|
||||
- Primary objective
|
||||
- Specific requirements
|
||||
- Constraints or limitations
|
||||
</details>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<action>Gather necessary context</action>
|
||||
<details>
|
||||
Review the minimal set of repository materials needed to act safely.
|
||||
Prefer extending existing guidance over introducing duplicated rules.
|
||||
</details>
|
||||
</step>
|
||||
</initialization_steps>
|
||||
|
||||
<main_workflow>
|
||||
<phase name="analysis">
|
||||
<description>Analyze the current state and requirements</description>
|
||||
<steps>
|
||||
<step>Identify affected components</step>
|
||||
<step>Assess impact of changes</step>
|
||||
<step>Plan implementation approach</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="implementation">
|
||||
<description>Execute the planned changes</description>
|
||||
<steps>
|
||||
<step>Create/modify necessary files</step>
|
||||
<step>Ensure consistency across codebase</step>
|
||||
<step>Add appropriate documentation</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="validation">
|
||||
<description>Verify the implementation</description>
|
||||
<steps>
|
||||
<step>Check for errors or inconsistencies</step>
|
||||
<step>Validate against requirements</step>
|
||||
<step>Ensure no regressions</step>
|
||||
</steps>
|
||||
</phase>
|
||||
</main_workflow>
|
||||
|
||||
<completion_criteria>
|
||||
<criterion>All requirements have been addressed</criterion>
|
||||
<criterion>Code follows project conventions</criterion>
|
||||
<criterion>Changes are properly documented</criterion>
|
||||
<criterion>No breaking changes introduced</criterion>
|
||||
</completion_criteria>
|
||||
</workflow_instructions>
|
||||
</template>
|
||||
</workflow_file_template>
|
||||
|
||||
<best_practices_template>
|
||||
<description>Template for best practices files (2_best_practices.xml)</description>
|
||||
<template>
|
||||
<best_practices>
|
||||
<general_principles>
|
||||
<principle priority="high">
|
||||
<name>Principle Name</name>
|
||||
<description>Detailed explanation of the principle</description>
|
||||
<rationale>Why this principle is important</rationale>
|
||||
<example>
|
||||
<scenario>When this applies</scenario>
|
||||
<good>Correct approach</good>
|
||||
<bad>What to avoid</bad>
|
||||
</example>
|
||||
</principle>
|
||||
</general_principles>
|
||||
|
||||
<code_conventions>
|
||||
<convention category="naming">
|
||||
<rule>Specific naming convention</rule>
|
||||
<examples>
|
||||
<good>goodExampleName</good>
|
||||
<bad>bad_example-name</bad>
|
||||
</examples>
|
||||
</convention>
|
||||
|
||||
<convention category="structure">
|
||||
<rule>How to structure code/files</rule>
|
||||
<template>
|
||||
// Example structure
|
||||
</template>
|
||||
</convention>
|
||||
</code_conventions>
|
||||
|
||||
<common_pitfalls>
|
||||
<pitfall>
|
||||
<description>Common mistake to avoid</description>
|
||||
<why_problematic>Explanation of issues it causes</why_problematic>
|
||||
<correct_approach>How to do it properly</correct_approach>
|
||||
</pitfall>
|
||||
</common_pitfalls>
|
||||
|
||||
<quality_checklist>
|
||||
<category name="before_starting">
|
||||
<item>Understand requirements fully</item>
|
||||
<item>Check existing implementations</item>
|
||||
</category>
|
||||
<category name="during_implementation">
|
||||
<item>Follow established patterns</item>
|
||||
<item>Write clear documentation</item>
|
||||
</category>
|
||||
<category name="before_completion">
|
||||
<item>Review all changes</item>
|
||||
<item>Verify requirements met</item>
|
||||
</category>
|
||||
</quality_checklist>
|
||||
</best_practices>
|
||||
</template>
|
||||
</best_practices_template>
|
||||
|
||||
<decision_guidance_template>
|
||||
<description>Template for decision criteria and guardrails (4_decision_guidance.xml)</description>
|
||||
<template>
|
||||
<decision_guidance>
|
||||
<principles>
|
||||
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||
</principles>
|
||||
|
||||
<boundaries>
|
||||
<rule>Define clear responsibilities and explicit handoff points to other modes</rule>
|
||||
</boundaries>
|
||||
|
||||
<validation>
|
||||
<rule>After changes, scan for contradictions and update examples to match</rule>
|
||||
</validation>
|
||||
</decision_guidance>
|
||||
</template>
|
||||
</decision_guidance_template>
|
||||
|
||||
<examples_file_template>
|
||||
<description>Template for example files (5_examples.xml)</description>
|
||||
<template>
|
||||
<complete_examples>
|
||||
<example name="descriptive_example_name">
|
||||
<scenario>
|
||||
Detailed description of the use case this example covers
|
||||
</scenario>
|
||||
|
||||
<user_request>
|
||||
The initial request from the user
|
||||
</user_request>
|
||||
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>First step description</description>
|
||||
<approach>
|
||||
Identify the relevant existing files/sections that need to change.
|
||||
Outcome: a shortlist of candidate paths or sections.
|
||||
</approach>
|
||||
<expected_outcome>What we learn from this step</expected_outcome>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Second step description</description>
|
||||
<approach>
|
||||
Review the top candidates and confirm the exact area to modify.
|
||||
Outcome: precise target sections and constraints.
|
||||
</approach>
|
||||
<analysis>How we interpret the results</analysis>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Implementation step</description>
|
||||
<approach>
|
||||
Apply the planned changes (localized edits when possible; full rewrites only when intentional).
|
||||
Outcome: required changes applied to the repository.
|
||||
</approach>
|
||||
</step>
|
||||
</workflow>
|
||||
|
||||
<completion>
|
||||
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||
</completion>
|
||||
|
||||
<key_takeaways>
|
||||
<takeaway>Important lesson from this example</takeaway>
|
||||
<takeaway>Pattern that can be reused</takeaway>
|
||||
</key_takeaways>
|
||||
</example>
|
||||
</complete_examples>
|
||||
</template>
|
||||
</examples_file_template>
|
||||
|
||||
<communication_template>
|
||||
<description>Template for communication guidelines (7_communication.xml)</description>
|
||||
<template>
|
||||
<communication_guidelines>
|
||||
<tone_and_style>
|
||||
<principle>Be direct and technical, not conversational</principle>
|
||||
<principle>Focus on actions taken and results achieved</principle>
|
||||
<avoid>
|
||||
<phrase>Great! I'll help you with that...</phrase>
|
||||
<phrase>Certainly! Let me...</phrase>
|
||||
<phrase>Sure thing!</phrase>
|
||||
</avoid>
|
||||
<prefer>
|
||||
<phrase>I'll analyze the codebase to...</phrase>
|
||||
<phrase>Implementing the requested changes...</phrase>
|
||||
<phrase>The analysis shows...</phrase>
|
||||
</prefer>
|
||||
</tone_and_style>
|
||||
|
||||
<verbosity>
|
||||
<policy>Keep narrative brief; prefer concise status updates</policy>
|
||||
<policy>Provide high detail only inside code/diffs and structured outputs</policy>
|
||||
<policy>Favor clarity over cleverness; avoid code-golf and cryptic names</policy>
|
||||
</verbosity>
|
||||
|
||||
<user_interaction>
|
||||
<when_to_ask_questions>
|
||||
<scenario>Missing critical information</scenario>
|
||||
<scenario>Multiple valid approaches exist</scenario>
|
||||
<scenario>Potential breaking changes</scenario>
|
||||
</when_to_ask_questions>
|
||||
|
||||
<question_format>
|
||||
<guideline>Be specific about what you need</guideline>
|
||||
<guideline>Provide actionable options</guideline>
|
||||
<guideline>Explain implications of choices</guideline>
|
||||
</question_format>
|
||||
</user_interaction>
|
||||
|
||||
<progress_updates>
|
||||
<when>During long-running operations</when>
|
||||
<format>
|
||||
<update>Analyzing [X] files for [purpose]...</update>
|
||||
<update>Implementing [feature] in [location]...</update>
|
||||
<update>Validating changes against [criteria]...</update>
|
||||
</format>
|
||||
</progress_updates>
|
||||
|
||||
<completion_messages>
|
||||
<structure>
|
||||
<element>What was accomplished</element>
|
||||
<element>Key changes made</element>
|
||||
<element>Any important notes or warnings</element>
|
||||
</structure>
|
||||
<avoid>
|
||||
<element>Questions at the end</element>
|
||||
<element>Offers for further assistance</element>
|
||||
<element>Conversational closings</element>
|
||||
</avoid>
|
||||
</completion_messages>
|
||||
</communication_guidelines>
|
||||
</template>
|
||||
</communication_template>
|
||||
</instruction_file_templates>
|
||||
@@ -0,0 +1,91 @@
|
||||
<complete_examples>
|
||||
<overview>
|
||||
Canonical examples for creating and editing Roo Code modes. Each example demonstrates structured workflows, least-privilege configuration, contradiction resolution, and completion formatting, without referencing runtime implementation details.
|
||||
</overview>
|
||||
|
||||
<example name="mode_editing_enhancement">
|
||||
<scenario>
|
||||
Edit the Test mode to add benchmark testing and performance guidance using Vitest's bench API.
|
||||
</scenario>
|
||||
<user_request>
|
||||
I want to edit the test mode to add benchmark testing support.
|
||||
</user_request>
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Clarify scope and features</description>
|
||||
<guidance>
|
||||
Ask the user a focused clarifying question to confirm which scope/features to include; provide 2–4 actionable options. Outcome: selected scope.
|
||||
</guidance>
|
||||
<expected_outcome>User selects: Add benchmark testing with Vitest bench API</expected_outcome>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Immerse in current mode config and instructions</description>
|
||||
<guidance>
|
||||
Review .roomodes, inventory .roo/rules-test recursively, and review .roo/rules-test/1_workflow.xml. Outcome: confirm roleDefinition, file restrictions, and existing workflows.
|
||||
</guidance>
|
||||
<analysis>Confirm roleDefinition, file restrictions, and existing workflows.</analysis>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Update roleDefinition in .roomodes</description>
|
||||
<guidance>
|
||||
Edit .roomodes to update the roleDefinition, adding benchmark testing and performance guidance topics. Outcome: roleDefinition updated to include performance/bench themes.
|
||||
</guidance>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Extend file restrictions to include .bench files</description>
|
||||
<guidance>
|
||||
Edit .roomodes to extend the fileRegex to include .bench.(ts|tsx|js|jsx) and update the description accordingly. Outcome: file restrictions now cover benchmark files.
|
||||
</guidance>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<description>Create benchmark guidance file</description>
|
||||
<guidance>
|
||||
Create a new file at .roo/rules-test/5_benchmark_testing.xml with guidance and examples. Outcome: new guidance file available to the mode.
|
||||
</guidance>
|
||||
<artifact_sample>
|
||||
<benchmark_testing_guide>
|
||||
<overview>Guidelines for performance benchmarks using Vitest bench API</overview>
|
||||
<benchmark_patterns>
|
||||
<pattern name="basic_benchmark">
|
||||
<description>Basic structure</description>
|
||||
<example>
|
||||
import { bench, describe } from 'vitest';
|
||||
|
||||
|
||||
describe('Array operations', () => {
|
||||
bench('Array.push', () => {
|
||||
const arr: number[] = [];
|
||||
for (let i = 0; i < 1000; i++) arr.push(i);
|
||||
});
|
||||
|
||||
bench('Array spread', () => {
|
||||
let arr: number[] = [];
|
||||
for (let i = 0; i < 1000; i++) arr = [...arr, i];
|
||||
});
|
||||
});
|
||||
</example>
|
||||
</pattern>
|
||||
</benchmark_patterns>
|
||||
<best_practices>
|
||||
<practice>Use meaningful names and isolate benchmarks</practice>
|
||||
<practice>Document expectations and thresholds</practice>
|
||||
</best_practices>
|
||||
</benchmark_testing_guide>
|
||||
</artifact_sample>
|
||||
</step>
|
||||
</workflow>
|
||||
|
||||
<completion>
|
||||
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||
</completion>
|
||||
|
||||
<key_takeaways>
|
||||
<takeaway>Important lesson from this example</takeaway>
|
||||
<takeaway>Pattern that can be reused</takeaway>
|
||||
</key_takeaways>
|
||||
</example>
|
||||
</complete_examples>
|
||||
@@ -0,0 +1,186 @@
|
||||
<mode_testing_validation>
|
||||
<overview>
|
||||
Guidelines for testing and validating newly created modes to ensure they function correctly and integrate well with the Roo Code ecosystem.
|
||||
</overview>
|
||||
|
||||
<validation_checklist>
|
||||
<category name="configuration_validation">
|
||||
<item priority="critical">
|
||||
<check>Mode slug is unique and follows naming conventions</check>
|
||||
<validation>No spaces, lowercase, hyphens only</validation>
|
||||
</item>
|
||||
<item priority="critical">
|
||||
<check>All required fields are present and non-empty</check>
|
||||
<fields>slug, name, roleDefinition, groups</fields>
|
||||
</item>
|
||||
<item priority="critical">
|
||||
<check>Avoid large customInstructions blocks in .roomodes</check>
|
||||
<validation>
|
||||
Prefer storing substantial mode guidance in XML files under <code>.roo/rules-[slug]/</code>.
|
||||
Small, high-level glue text in <code>customInstructions</code> is acceptable when needed.
|
||||
</validation>
|
||||
</item>
|
||||
<item priority="high">
|
||||
<check>File restrictions use valid regex patterns</check>
|
||||
<test_method>Validate by comparing the regex pattern against the intended file sets; confirm patterns match intended files and avoid overbroad matches.</test_method>
|
||||
</item>
|
||||
<item priority="high">
|
||||
<check>whenToUse clearly differentiates from other modes</check>
|
||||
<validation>Compare with existing mode descriptions</validation>
|
||||
</item>
|
||||
</category>
|
||||
|
||||
<category name="instruction_validation">
|
||||
<item>
|
||||
<check>XML files are well-formed and valid</check>
|
||||
<validation>No syntax errors, proper closing tags</validation>
|
||||
</item>
|
||||
<item>
|
||||
<check>Instructions follow XML best practices</check>
|
||||
<validation>Semantic tag names, proper nesting</validation>
|
||||
</item>
|
||||
<item>
|
||||
<check>Examples avoid runtime implementation details</check>
|
||||
<validation>Examples align with current permissions and constraints</validation>
|
||||
</item>
|
||||
<item>
|
||||
<check>File paths in examples are consistent</check>
|
||||
<validation>Use project-relative paths</validation>
|
||||
</item>
|
||||
</category>
|
||||
|
||||
<category name="functional_testing">
|
||||
<item>
|
||||
<check>Mode appears in mode list</check>
|
||||
<test>Switch to the new mode and verify it loads</test>
|
||||
</item>
|
||||
<item>
|
||||
<check>Permissions work as expected</check>
|
||||
<test>Verify representative actions for each permission category</test>
|
||||
</item>
|
||||
<item>
|
||||
<check>File restrictions are enforced</check>
|
||||
<test>Attempt to edit allowed and restricted files</test>
|
||||
</item>
|
||||
<item>
|
||||
<check>Mode handles edge cases gracefully</check>
|
||||
<test>Test with minimal input, errors, edge cases</test>
|
||||
</item>
|
||||
</category>
|
||||
</validation_checklist>
|
||||
|
||||
<testing_workflow>
|
||||
<step number="1">
|
||||
<title>Configuration Testing</title>
|
||||
<actions>
|
||||
<action>Verify mode appears in available modes list</action>
|
||||
<action>Check that mode metadata displays correctly</action>
|
||||
<action>Confirm mode can be activated</action>
|
||||
</actions>
|
||||
<verification>Confirm via user feedback. If unclear, ask a focused clarifying question with options like: "Visible and switchable", "Not visible", or "Visible but errors".</verification>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<title>Permission Testing</title>
|
||||
<test_cases>
|
||||
<test case="read_permissions">
|
||||
<action>Verify read access works for representative files</action>
|
||||
<expected>All read operations should work</expected>
|
||||
</test>
|
||||
<test case="edit_restrictions">
|
||||
<action>Try editing allowed file types</action>
|
||||
<expected>Edits succeed for matching patterns</expected>
|
||||
</test>
|
||||
<test case="edit_restrictions_negative">
|
||||
<action>Try editing restricted file types</action>
|
||||
<expected>An explicit permission/restriction error for non-matching files</expected>
|
||||
</test>
|
||||
</test_cases>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<title>Workflow Testing</title>
|
||||
<actions>
|
||||
<action>Execute main workflow from start to finish</action>
|
||||
<action>Test each decision point</action>
|
||||
<action>Verify error handling</action>
|
||||
<action>Check completion criteria</action>
|
||||
</actions>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<title>Integration Testing</title>
|
||||
<areas>
|
||||
<area>Orchestrator mode compatibility</area>
|
||||
<area>Mode switching functionality</area>
|
||||
<area>Capability handoff between modes</area>
|
||||
<area>Consistent behavior with other modes</area>
|
||||
</areas>
|
||||
</step>
|
||||
</testing_workflow>
|
||||
|
||||
<common_issues>
|
||||
<issue type="configuration">
|
||||
<problem>Mode doesn't appear in list</problem>
|
||||
<causes>
|
||||
<cause>Syntax error in YAML</cause>
|
||||
<cause>Invalid mode slug</cause>
|
||||
<cause>File not saved</cause>
|
||||
</causes>
|
||||
<solution>Check YAML syntax, validate slug format</solution>
|
||||
</issue>
|
||||
|
||||
<issue type="permissions">
|
||||
<problem>File restriction not working</problem>
|
||||
<causes>
|
||||
<cause>Invalid regex pattern</cause>
|
||||
<cause>Escaping issues in regex</cause>
|
||||
<cause>Wrong file path format</cause>
|
||||
</causes>
|
||||
<solution>Test regex pattern, use proper escaping</solution>
|
||||
<example>
|
||||
# Wrong: *.ts (glob pattern)
|
||||
|
||||
# Right: .*\.ts$ (regex pattern)
|
||||
</example>
|
||||
</issue>
|
||||
|
||||
<issue type="behavior">
|
||||
<problem>Mode not following instructions</problem>
|
||||
<causes>
|
||||
<cause>Instructions not in .roo/rules-[slug]/ folder</cause>
|
||||
<cause>XML parsing errors</cause>
|
||||
<cause>Conflicting instructions</cause>
|
||||
</causes>
|
||||
<solution>Verify file locations and XML validity</solution>
|
||||
</issue>
|
||||
</common_issues>
|
||||
|
||||
<debugging_practices>
|
||||
<practice>
|
||||
<name>Directory/file inventory</name>
|
||||
<usage>Verify instruction files exist in the correct location</usage>
|
||||
<guidance>Check the .roo directory structure and ensure the expected rules-[slug] folder and XML files exist.</guidance>
|
||||
</practice>
|
||||
|
||||
<practice>
|
||||
<name>Configuration review</name>
|
||||
<usage>Check mode configuration syntax</usage>
|
||||
<guidance>Review .roomodes to validate YAML structure and entries for the target mode.</guidance>
|
||||
</practice>
|
||||
|
||||
<practice>
|
||||
<name>Regex validation</name>
|
||||
<usage>Test file restriction patterns</usage>
|
||||
<guidance>Use targeted checks conceptually to confirm fileRegex patterns match intended files and exclude others.</guidance>
|
||||
</practice>
|
||||
</debugging_practices>
|
||||
|
||||
<best_practices>
|
||||
<practice>Test incrementally as you build the mode</practice>
|
||||
<practice>Start with minimal configuration and add complexity</practice>
|
||||
<practice>Document any special requirements or dependencies</practice>
|
||||
<practice>Consider edge cases and error scenarios</practice>
|
||||
<practice>Get feedback from potential users of the mode</practice>
|
||||
</best_practices>
|
||||
</mode_testing_validation>
|
||||
@@ -0,0 +1,194 @@
|
||||
<validation_cohesion_checking>
|
||||
<overview>
|
||||
Guidelines for thoroughly validating mode changes to ensure cohesion,
|
||||
consistency, and prevent contradictions across all mode components.
|
||||
</overview>
|
||||
|
||||
<validation_principles>
|
||||
<principle name="comprehensive_review">
|
||||
<description>
|
||||
Every change must be reviewed in context of the entire mode
|
||||
</description>
|
||||
<checklist>
|
||||
<item>Read all existing XML instruction files</item>
|
||||
<item>Verify new changes align with existing patterns</item>
|
||||
<item>Check for duplicate or conflicting instructions</item>
|
||||
<item>Ensure terminology is consistent throughout</item>
|
||||
</checklist>
|
||||
</principle>
|
||||
|
||||
<principle name="focused_questioning">
|
||||
<description>
|
||||
Ask focused clarifying questions only when needed to de-risk the work
|
||||
</description>
|
||||
<when_to_ask>
|
||||
<scenario>Critical details are missing (cannot proceed safely)</scenario>
|
||||
<scenario>Multiple valid approaches exist and the tradeoffs matter</scenario>
|
||||
<scenario>Proposed changes are risky/irreversible (permissions, deletions, broad refactors)</scenario>
|
||||
<scenario>A change may require widening permissions or fileRegex patterns</scenario>
|
||||
</when_to_ask>
|
||||
<example>
|
||||
In practice: ask a focused question with 2–4 actionable options.
|
||||
Example:
|
||||
- Question: "This change may affect file permissions. Should we also update the fileRegex patterns?"
|
||||
- Options:
|
||||
1) "Yes, include the new file types in the regex"
|
||||
2) "No, keep current restrictions"
|
||||
3) "I need to list the file types I’ll work with"
|
||||
4) "Show me the current restrictions first"
|
||||
</example>
|
||||
</principle>
|
||||
|
||||
<principle name="contradiction_detection">
|
||||
<description>
|
||||
Actively search for and resolve contradictions
|
||||
</description>
|
||||
<common_contradictions>
|
||||
<contradiction>
|
||||
<type>Permission Mismatch</type>
|
||||
<description>Instructions reference permissions the mode doesn't have</description>
|
||||
<resolution>Either grant the permission or update the instructions</resolution>
|
||||
</contradiction>
|
||||
<contradiction>
|
||||
<type>Workflow Conflicts</type>
|
||||
<description>Different XML files describe conflicting workflows</description>
|
||||
<resolution>Consolidate workflows and ensure single source of truth</resolution>
|
||||
</contradiction>
|
||||
<contradiction>
|
||||
<type>Role Confusion</type>
|
||||
<description>Mode's roleDefinition doesn't match its actual scope/permissions</description>
|
||||
<resolution>Update roleDefinition to accurately reflect the mode's purpose</resolution>
|
||||
</contradiction>
|
||||
</common_contradictions>
|
||||
</principle>
|
||||
</validation_principles>
|
||||
|
||||
<validation_workflow>
|
||||
<phase name="pre_change_analysis">
|
||||
<description>Before making any changes</description>
|
||||
<steps>
|
||||
<step>Read and understand all existing mode files</step>
|
||||
<step>Create a mental model of current mode behavior</step>
|
||||
<step>Identify potential impact areas</step>
|
||||
<step>Ask clarifying questions about intended changes</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="change_implementation">
|
||||
<description>While making changes</description>
|
||||
<steps>
|
||||
<step>Document each change and its rationale</step>
|
||||
<step>Cross-reference with other files after each change</step>
|
||||
<step>Verify examples still work with new changes</step>
|
||||
<step>Update related documentation immediately</step>
|
||||
</steps>
|
||||
</phase>
|
||||
|
||||
<phase name="post_change_validation">
|
||||
<description>After changes are complete</description>
|
||||
<validation_checklist>
|
||||
<category name="structural_validation">
|
||||
<check>All XML files are well-formed and valid</check>
|
||||
<check>File naming follows established patterns</check>
|
||||
<check>Tag names are consistent across files</check>
|
||||
<check>No orphaned or unused instructions</check>
|
||||
</category>
|
||||
|
||||
<category name="content_validation">
|
||||
<check>roleDefinition accurately describes the mode</check>
|
||||
<check>whenToUse is clear and distinguishable</check>
|
||||
<check>Permissions match instruction requirements</check>
|
||||
<check>File restrictions align with mode purpose</check>
|
||||
<check>Examples are accurate and functional</check>
|
||||
</category>
|
||||
|
||||
<category name="integration_validation">
|
||||
<check>Mode boundaries are well-defined</check>
|
||||
<check>Handoff points to other modes are clear</check>
|
||||
<check>No overlap with other modes' responsibilities</check>
|
||||
<check>Orchestrator can correctly route to this mode</check>
|
||||
</category>
|
||||
</validation_checklist>
|
||||
</phase>
|
||||
</validation_workflow>
|
||||
|
||||
<cohesion_patterns>
|
||||
<pattern name="consistent_voice">
|
||||
<description>Maintain consistent tone and terminology</description>
|
||||
<guidelines>
|
||||
<guideline>Use the same terms for the same concepts throughout</guideline>
|
||||
<guideline>Keep instruction style consistent across files</guideline>
|
||||
<guideline>Maintain the same level of detail in similar sections</guideline>
|
||||
</guidelines>
|
||||
</pattern>
|
||||
|
||||
<pattern name="logical_flow">
|
||||
<description>Ensure instructions flow logically</description>
|
||||
<guidelines>
|
||||
<guideline>Prerequisites come before dependent steps</guideline>
|
||||
<guideline>Complex concepts build on simpler ones</guideline>
|
||||
<guideline>Examples follow the explained patterns</guideline>
|
||||
</guidelines>
|
||||
</pattern>
|
||||
|
||||
<pattern name="complete_coverage">
|
||||
<description>Ensure all aspects are covered without gaps</description>
|
||||
<guidelines>
|
||||
<guideline>Every mentioned concept has decision guidance (what/when) without runtime implementation details</guideline>
|
||||
<guideline>All workflows have complete examples</guideline>
|
||||
<guideline>Error scenarios are addressed</guideline>
|
||||
</guidelines>
|
||||
</pattern>
|
||||
</cohesion_patterns>
|
||||
|
||||
<validation_questions>
|
||||
<question_set name="before_changes">
|
||||
<prompt>
|
||||
Before we proceed with changes, ensure the main goal is clear. Suggested options:
|
||||
- Add new functionality while keeping existing features
|
||||
- Fix issues with current implementation
|
||||
- Refactor for better organization
|
||||
- Expand the mode's scope into new areas
|
||||
</prompt>
|
||||
</question_set>
|
||||
|
||||
<question_set name="during_changes">
|
||||
<prompt>
|
||||
This change might affect other parts of the mode. Choose an approach:
|
||||
- Update all affected areas to maintain consistency
|
||||
- Keep the existing behavior for backward compatibility
|
||||
- Create a migration path from old to new behavior
|
||||
- Review the impact first
|
||||
</prompt>
|
||||
</question_set>
|
||||
|
||||
<question_set name="after_changes">
|
||||
<prompt>
|
||||
Post-change testing focus areas:
|
||||
- Test the new workflow end-to-end
|
||||
- Verify file permissions work correctly
|
||||
- Check integration with other modes
|
||||
- Review all changes one more time
|
||||
</prompt>
|
||||
</question_set>
|
||||
</validation_questions>
|
||||
|
||||
<red_flags>
|
||||
<flag priority="high">
|
||||
<description>Instructions reference permissions not in the mode's groups</description>
|
||||
<action>Either add the permission group or remove/update the instruction</action>
|
||||
</flag>
|
||||
<flag priority="high">
|
||||
<description>File regex doesn't match described file types</description>
|
||||
<action>Update regex pattern to match intended files</action>
|
||||
</flag>
|
||||
<flag priority="medium">
|
||||
<description>Examples don't follow stated best practices</description>
|
||||
<action>Update examples to demonstrate best practices</action>
|
||||
</flag>
|
||||
<flag priority="medium">
|
||||
<description>Duplicate instructions in different files</description>
|
||||
<action>Consolidate to single location and reference</action>
|
||||
</flag>
|
||||
</red_flags>
|
||||
</validation_cohesion_checking>
|
||||
@@ -0,0 +1,51 @@
|
||||
<global_modes_reference>
|
||||
<overview>
|
||||
This reference documents how global (system-wide) modes work, where they live, and how they interact
|
||||
with workspace-scoped modes.
|
||||
</overview>
|
||||
|
||||
<locations>
|
||||
<workspace>
|
||||
<file>.roomodes</file>
|
||||
<scope>Per-workspace (project) modes</scope>
|
||||
</workspace>
|
||||
|
||||
<global>
|
||||
<file>Global custom modes settings file (stored in VS Code globalStorage; exact path is environment-specific)</file>
|
||||
<scope>System-wide modes for Roo Code</scope>
|
||||
<notes>
|
||||
This file is created automatically on Roo Code startup if it does not exist.
|
||||
</notes>
|
||||
</global>
|
||||
</locations>
|
||||
|
||||
<precedence>
|
||||
<rule>
|
||||
When a mode with the same slug exists in both locations, the workspace (.roomodes) version takes precedence.
|
||||
</rule>
|
||||
<implications>
|
||||
<implication>
|
||||
Editing the global mode may have no visible effect inside a workspace that overrides the same slug.
|
||||
</implication>
|
||||
<implication>
|
||||
To change behavior in one repo only, prefer editing .roomodes.
|
||||
</implication>
|
||||
</implications>
|
||||
</precedence>
|
||||
|
||||
<workflow_guidance>
|
||||
<decision>
|
||||
<rule>Default to editing .roomodes unless the user explicitly requests global scope.</rule>
|
||||
<rule>
|
||||
If the user asks for global scope, first check whether a workspace override exists for the same slug.
|
||||
If it does, explain the precedence and offer to edit both.
|
||||
</rule>
|
||||
</decision>
|
||||
|
||||
<safe_editing_principles>
|
||||
<principle>
|
||||
Prefer minimal, targeted changes and preserve YAML formatting.
|
||||
</principle>
|
||||
</safe_editing_principles>
|
||||
</workflow_guidance>
|
||||
</global_modes_reference>
|
||||
@@ -0,0 +1,116 @@
|
||||
<workflow_instructions>
|
||||
<mode_overview>
|
||||
Create, edit, and validate Agent Skills packages (SKILL.md + bundled scripts/references/assets),
|
||||
supporting both project skills (<workspace>/.roo/skills*) and global skills (<home>/.roo/skills*),
|
||||
including generic and mode-specific skills.
|
||||
</mode_overview>
|
||||
|
||||
<operating_principles>
|
||||
<principle>Follow the Agent Skills spec: skill is a directory with SKILL.md (required) and YAML frontmatter.</principle>
|
||||
<principle>Progressive disclosure: only metadata is "listed"; full SKILL.md and other files are loaded/used only when needed.</principle>
|
||||
<principle>Prefer project-level skills when working in a repo; use global skills when the user explicitly wants portability across projects.</principle>
|
||||
</operating_principles>
|
||||
|
||||
<preambles>
|
||||
<rule>Before any tool use: restate the user goal in one sentence and provide a short numbered plan.</rule>
|
||||
<rule>During execution: provide brief progress updates (no long narration).</rule>
|
||||
<rule>Finish: summarize what changed and how it meets the spec.</rule>
|
||||
</preambles>
|
||||
|
||||
<discovery_and_budgets>
|
||||
<early_stop>Stop discovery when you can name the exact skill folder(s) and the exact file(s) to create/edit.</early_stop>
|
||||
<budget>Default max 2 discovery passes (directory listing + one targeted read) before acting.</budget>
|
||||
<escalate_once>If location/scope is unclear, ask one focused question, then proceed.</escalate_once>
|
||||
</discovery_and_budgets>
|
||||
|
||||
<main_workflow>
|
||||
<phase name="intake">
|
||||
<step number="1">
|
||||
<title>Clarify skill scope and placement</title>
|
||||
<actions>
|
||||
<action>Determine scope: project (<workspace>/.roo/skills*) vs global (<home>/.roo/skills*)</action>
|
||||
<action>Determine specificity: generic (skills/) vs mode-specific (skills-<mode>/)</action>
|
||||
<action>Determine operation: create new skill, edit existing, or audit</action>
|
||||
<action>Default to project + generic unless the user explicitly requests global and/or mode-specific</action>
|
||||
</actions>
|
||||
<acceptance_criteria>
|
||||
<criterion>Target root directory and skill name are unambiguous</criterion>
|
||||
</acceptance_criteria>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<title>Establish the canonical skill name</title>
|
||||
<actions>
|
||||
<action>Choose a spec-compliant name (lowercase letters, numbers, hyphens; 1–64 chars; no leading/trailing hyphen; no consecutive hyphens)</action>
|
||||
<action>Ensure directory (or symlink alias) name matches frontmatter name exactly</action>
|
||||
</actions>
|
||||
</step>
|
||||
</phase>
|
||||
|
||||
<phase name="authoring">
|
||||
<step number="3">
|
||||
<title>Draft SKILL.md frontmatter and outline</title>
|
||||
<actions>
|
||||
<action>Write YAML frontmatter with required fields: name, description</action>
|
||||
<action>Optionally include license, compatibility, metadata, allowed-tools (do not assume enforcement)</action>
|
||||
<action>Write a concise "When to use" section and a step-by-step workflow section</action>
|
||||
</actions>
|
||||
<quality_gates>
|
||||
<gate>Description explains what the skill does AND when to use it, with keywords for matching</gate>
|
||||
<gate>Instructions are actionable and ordered</gate>
|
||||
</quality_gates>
|
||||
</step>
|
||||
|
||||
<step number="3.1">
|
||||
<title>Choose structure (single-file vs multi-file)</title>
|
||||
<actions>
|
||||
<action>Default to SKILL.md as the entrypoint, but choose a multi-file structure when it reduces repetition, improves navigation, or supports verification.</action>
|
||||
<action>Use references/ for long-lived guidance (APIs, checklists, domain subtopics).</action>
|
||||
<action>Use scripts/ for deterministic automation/validation; prefer executable scripts for repeatable checks.</action>
|
||||
<action>Use assets/ for templates or example artifacts that should not live inline in SKILL.md.</action>
|
||||
<action>Link all reference files directly from SKILL.md; avoid multi-hop references.</action>
|
||||
</actions>
|
||||
<acceptance_criteria>
|
||||
<criterion>SKILL.md makes it clear which linked file to read next (and when) and which scripts to execute (and when)</criterion>
|
||||
</acceptance_criteria>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<title>Add optional resources (only if they improve execution)</title>
|
||||
<actions>
|
||||
<action>Create scripts/ only when automation is genuinely useful and the user explicitly agrees; otherwise keep instructions manual</action>
|
||||
<action>Create references/ only when it materially improves execution and the user explicitly agrees; keep SKILL.md lean</action>
|
||||
<action>Create assets/ only when it materially improves execution and the user explicitly agrees (templates, example files, diagrams)</action>
|
||||
</actions>
|
||||
</step>
|
||||
</phase>
|
||||
|
||||
<phase name="validation">
|
||||
<step number="5">
|
||||
<title>Validate spec compliance (minimum checks)</title>
|
||||
<checks>
|
||||
<check>SKILL.md exists at skill root</check>
|
||||
<check>Frontmatter contains name + description</check>
|
||||
<check>Frontmatter name matches directory (or symlink alias) name</check>
|
||||
<check>Name constraints: 1–64 chars; lowercase letters/numbers/hyphens only; no leading/trailing hyphen; no consecutive hyphens</check>
|
||||
<check>Description constraints: non-empty after trimming; max 1024 characters</check>
|
||||
<check>File references use relative paths and remain shallow</check>
|
||||
</checks>
|
||||
</step>
|
||||
|
||||
<step number="6">
|
||||
<title>Handoff and activation guidance</title>
|
||||
<actions>
|
||||
<action>Ensure the description includes trigger keywords so the model can match it reliably</action>
|
||||
<action>Ensure the first section tells the model when NOT to use the skill and what to do instead</action>
|
||||
</actions>
|
||||
</step>
|
||||
</phase>
|
||||
</main_workflow>
|
||||
|
||||
<completion_criteria>
|
||||
<criterion>Skill folder structure is correct and includes SKILL.md</criterion>
|
||||
<criterion>Frontmatter passes required constraints</criterion>
|
||||
<criterion>Instructions are clear, safe, and usable</criterion>
|
||||
</completion_criteria>
|
||||
</workflow_instructions>
|
||||
@@ -0,0 +1,94 @@
|
||||
<best_practices>
|
||||
<authoring>
|
||||
<guideline priority="high">
|
||||
<rule>Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes.</rule>
|
||||
<rationale>Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Write the frontmatter description in third person, and include both what the skill does and when to use it.</rule>
|
||||
<rationale>The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files.</rule>
|
||||
<rationale>Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why).</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid.</rule>
|
||||
<rationale>Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers.</rule>
|
||||
<rationale>Improves selection accuracy during skill matching.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Make the description actionable: describe what the skill DOES and when to use it.</rule>
|
||||
<rationale>Vague descriptions reduce match quality and increase false positives/negatives.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Start SKILL.md with "When to use" and "When NOT to use".</rule>
|
||||
<rationale>Prevents accidental activation and reduces false positives.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="high">
|
||||
<rule>Prefer short, numbered steps with explicit inputs/outputs.</rule>
|
||||
<rationale>Agents follow procedural instructions more reliably than prose.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="medium">
|
||||
<rule>Use progressive disclosure: keep SKILL.md concise; move deep reference into references/.</rule>
|
||||
<rationale>Minimizes context usage while preserving detail on demand.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="medium">
|
||||
<rule>Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary).</rule>
|
||||
<rationale>Too many options reduces reliability and increases variance in execution.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="medium">
|
||||
<rule>When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md.</rule>
|
||||
<rationale>Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="low">
|
||||
<rule>For longer reference files, include a short table of contents near the top to make selective reading easier.</rule>
|
||||
<rationale>Helps the agent jump to the correct section without reading the entire file.</rationale>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="low">
|
||||
<rule>Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md.</rule>
|
||||
<rationale>Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected.</rationale>
|
||||
</guideline>
|
||||
|
||||
<example_refinement>
|
||||
<user_phrase>I want a skill for making API docs</user_phrase>
|
||||
<refined_description>Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments</refined_description>
|
||||
</example_refinement>
|
||||
</authoring>
|
||||
|
||||
<structure>
|
||||
<guideline priority="high">
|
||||
<rule>Keep skill names stable; treat renames as breaking changes.</rule>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="medium">
|
||||
<rule>Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh).</rule>
|
||||
</guideline>
|
||||
|
||||
<guideline priority="medium">
|
||||
<rule>Make intent explicit for scripts: state whether the agent should execute the script or read it as reference.</rule>
|
||||
<rationale>Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters.</rationale>
|
||||
</guideline>
|
||||
</structure>
|
||||
|
||||
<compatibility>
|
||||
<guideline priority="medium">
|
||||
<rule>Use the optional compatibility field only when it meaningfully constrains runtime requirements.</rule>
|
||||
</guideline>
|
||||
</compatibility>
|
||||
</best_practices>
|
||||
@@ -0,0 +1,100 @@
|
||||
<common_patterns>
|
||||
<skill_folder_patterns>
|
||||
<pattern name="project_generic">
|
||||
<description>Project skill available across all modes in this repo</description>
|
||||
<path>./.roo/skills/<skill-name>/SKILL.md</path>
|
||||
</pattern>
|
||||
|
||||
<pattern name="project_mode_specific">
|
||||
<description>Project skill available only in a specific mode</description>
|
||||
<path>./.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||
</pattern>
|
||||
|
||||
<pattern name="global_generic">
|
||||
<description>Global skill available across all workspaces</description>
|
||||
<path><home>/.roo/skills/<skill-name>/SKILL.md</path>
|
||||
</pattern>
|
||||
|
||||
<pattern name="global_mode_specific">
|
||||
<description>Global skill available only in a specific mode</description>
|
||||
<path><home>/.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||
</pattern>
|
||||
</skill_folder_patterns>
|
||||
|
||||
<skill_structure_guidance>
|
||||
<default>
|
||||
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||
<rule>Add additional files only when they materially improve navigation, reuse, or verification.</rule>
|
||||
</default>
|
||||
|
||||
<optional_folders>
|
||||
<folder name="references">
|
||||
<use_for>Optional deep dives (APIs, schemas, checklists, edge cases)</use_for>
|
||||
<rule>Link directly from SKILL.md; avoid multi-hop references.</rule>
|
||||
</folder>
|
||||
<folder name="scripts">
|
||||
<use_for>Deterministic validation or automation (prefer execute-first workflows)</use_for>
|
||||
<rule>SKILL.md must state whether to execute the script or read it as reference.</rule>
|
||||
</folder>
|
||||
<folder name="assets">
|
||||
<use_for>Reusable templates and example artifacts</use_for>
|
||||
</folder>
|
||||
</optional_folders>
|
||||
</skill_structure_guidance>
|
||||
|
||||
<linked_file_handling>
|
||||
<rule>Do not assume linked file contents unless they have been explicitly read.</rule>
|
||||
<rule>Prefer reading the minimum necessary linked file(s) for the current task.</rule>
|
||||
</linked_file_handling>
|
||||
|
||||
<path_conventions>
|
||||
<rule>Use forward slashes in paths (e.g., references/guide.md) for cross-platform compatibility.</rule>
|
||||
</path_conventions>
|
||||
|
||||
<override_priority>
|
||||
<note>When the same skill name exists in multiple locations, prefer the highest-precedence one.</note>
|
||||
<order>
|
||||
<item>Project mode-specific: ./.roo/skills-<mode>/<skill-name>/</item>
|
||||
<item>Project generic: ./.roo/skills/<skill-name>/</item>
|
||||
<item>Global mode-specific: <home>/.roo/skills-<mode>/<skill-name>/</item>
|
||||
<item>Global generic: <home>/.roo/skills/<skill-name>/</item>
|
||||
</order>
|
||||
</override_priority>
|
||||
|
||||
<skill_md_minimum_format>
|
||||
<note>SKILL.md must start with YAML frontmatter including name and description.</note>
|
||||
<frontmatter_example><![CDATA[
|
||||
--- name: your-skill-name description: When to use this skill and what it does (include matching keywords) ---
|
||||
# When to use
|
||||
# When NOT to use
|
||||
# Inputs required
|
||||
# Workflow 1) ... 2) ...
|
||||
# Examples
|
||||
# Troubleshooting
|
||||
]]></frontmatter_example>
|
||||
</skill_md_minimum_format>
|
||||
|
||||
<recommended_skill_md_sections>
|
||||
<section>Title (matches intent; human-readable)</section>
|
||||
<section>When to use this skill</section>
|
||||
<section>When NOT to use this skill</section>
|
||||
<section>Inputs required from the user</section>
|
||||
<section>Workflow (numbered)</section>
|
||||
<section>Examples (minimal, realistic)</section>
|
||||
<section>Troubleshooting / edge cases</section>
|
||||
</recommended_skill_md_sections>
|
||||
|
||||
<validation_rules>
|
||||
<name_constraints>
|
||||
<rule>1–64 characters</rule>
|
||||
<rule>Lowercase letters, numbers, and hyphens only</rule>
|
||||
<rule>No leading or trailing hyphen</rule>
|
||||
<rule>No consecutive hyphens</rule>
|
||||
<rule>Must match the directory name exactly</rule>
|
||||
</name_constraints>
|
||||
<description_constraints>
|
||||
<rule>Non-empty after trimming</rule>
|
||||
<rule>Max 1024 characters</rule>
|
||||
</description_constraints>
|
||||
</validation_rules>
|
||||
</common_patterns>
|
||||
@@ -0,0 +1,78 @@
|
||||
<decision_guidance>
|
||||
<principles>
|
||||
<principle>Prefer the smallest change that satisfies the request.</principle>
|
||||
<principle>Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files.</principle>
|
||||
<principle>Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous.</principle>
|
||||
</principles>
|
||||
|
||||
<progressive_disclosure_guardrails>
|
||||
<overview>
|
||||
Progressive disclosure is a tool to reduce token load and improve navigation.
|
||||
It is not a default requirement.
|
||||
|
||||
Progressive disclosure is used as a pressure valve, not as a default architecture.
|
||||
</overview>
|
||||
|
||||
<default_policy>
|
||||
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||
<rule>Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost.</rule>
|
||||
</default_policy>
|
||||
|
||||
<good_reasons_to_split>
|
||||
<rule>SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details.</rule>
|
||||
<rule>The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient.</rule>
|
||||
<rule>High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow.</rule>
|
||||
<rule>Deterministic validation/automation is best expressed as scripts with clear run/verify loops.</rule>
|
||||
</good_reasons_to_split>
|
||||
|
||||
<bad_reasons_to_split>
|
||||
<rule>Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit.</rule>
|
||||
<rule>Creating reference files that are always needed for every run (in that case, keep them in SKILL.md).</rule>
|
||||
<rule>Creating multi-hop chains (SKILL.md → reference.md → details.md) that require chasing links.</rule>
|
||||
</bad_reasons_to_split>
|
||||
|
||||
<decision_test>
|
||||
<rule>If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md.</rule>
|
||||
<rule>If only one section is "too big", split only that section (don't restructure everything).</rule>
|
||||
</decision_test>
|
||||
</progressive_disclosure_guardrails>
|
||||
|
||||
<scope_selection>
|
||||
<default>
|
||||
<rule>Default to project skills under <workspace>/.roo/skills* unless the user explicitly requests global skills.</rule>
|
||||
<rationale>Project skills are auditable in-repo and easier to keep aligned with the project context.</rationale>
|
||||
</default>
|
||||
|
||||
<global_trigger>
|
||||
<rule>Use global skills only when the user explicitly wants portability across projects.</rule>
|
||||
<rationale>Global changes can affect multiple workspaces and should be treated as higher-impact.</rationale>
|
||||
</global_trigger>
|
||||
|
||||
<mode_specific_trigger>
|
||||
<rule>Create mode-specific skills only when the skill is intentionally scoped to a single mode.</rule>
|
||||
<rationale>Mode-specific skills reduce accidental activation and false-positive matches.</rationale>
|
||||
</mode_specific_trigger>
|
||||
</scope_selection>
|
||||
|
||||
<breaking_change_rules>
|
||||
<rename_policy>
|
||||
<rule>Treat renaming a skill directory (and therefore the skill name) as a breaking change.</rule>
|
||||
<rule>Do not rename without explicit user confirmation.</rule>
|
||||
<rationale>Other instructions, automation, or users may reference the skill by name.</rationale>
|
||||
</rename_policy>
|
||||
|
||||
<name_mismatch_resolution>
|
||||
<rule>Resolve directory/frontmatter mismatches before making additional edits.</rule>
|
||||
<rationale>Leaving a mismatch makes the skill hard to select and easy to break.</rationale>
|
||||
</name_mismatch_resolution>
|
||||
</breaking_change_rules>
|
||||
|
||||
<resource_creation_rules>
|
||||
<rule>Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees.</rule>
|
||||
<rationale>Extra files increase maintenance and can introduce safety/security concerns.</rationale>
|
||||
</resource_creation_rules>
|
||||
|
||||
<handoffs>
|
||||
<rule>If the user asks for edits outside <workspace>/.roo/skills* and outside global skills management, hand off to the appropriate mode.</rule>
|
||||
</handoffs>
|
||||
</decision_guidance>
|
||||
@@ -0,0 +1,77 @@
|
||||
<complete_examples>
|
||||
<example name="create_project_mode_specific_skill">
|
||||
<scenario>Create a new mode-specific project skill to standardize a workflow in one mode.</scenario>
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Confirm scope and name</description>
|
||||
<expected_outcome>Target path is ./.roo/skills-<mode>/<skill-name>/SKILL.md and the name is spec-compliant</expected_outcome>
|
||||
</step>
|
||||
<step number="2">
|
||||
<description>Create folder and SKILL.md with required frontmatter and clear sections</description>
|
||||
<expected_outcome>Skill is discoverable and has actionable instructions</expected_outcome>
|
||||
</step>
|
||||
<step number="3">
|
||||
<description>Validate name/description constraints and directory-name match</description>
|
||||
<expected_outcome>Spec-compliant frontmatter</expected_outcome>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<example name="create_multi_file_skill_with_references_and_scripts">
|
||||
<scenario>
|
||||
Create a project skill that includes an entrypoint SKILL.md plus reference material and a validation script.
|
||||
The goal is progressive disclosure: only read references when needed, and execute scripts for deterministic checks.
|
||||
</scenario>
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Choose structure based on fragility and size</description>
|
||||
<expected_outcome>
|
||||
Use SKILL.md as the entrypoint, references/ for long-lived guidance, and scripts/ for validation/automation.
|
||||
</expected_outcome>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<description>Draft SKILL.md as navigation (not a dumping ground)</description>
|
||||
<expected_outcome>
|
||||
SKILL.md contains:
|
||||
- Frontmatter (name/description)
|
||||
- When to use / When NOT to use
|
||||
- A numbered workflow with explicit "read this file when..." pointers
|
||||
- A "Files" section that links one level deep:
|
||||
- references/SCHEMA.md (read when needing field definitions)
|
||||
- references/TROUBLESHOOTING.md (read when validation fails)
|
||||
- scripts/validate_input.(sh|js|py) (execute to validate intermediate outputs)
|
||||
</expected_outcome>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<description>Create references with table-of-contents style headings</description>
|
||||
<expected_outcome>
|
||||
Each references/*.md file starts with a short contents list so the agent can jump to relevant sections.
|
||||
</expected_outcome>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<description>Make script intent explicit</description>
|
||||
<expected_outcome>
|
||||
SKILL.md clearly states whether the script should be executed (preferred) or read as reference.
|
||||
The script produces verifiable output (e.g., JSON report or "OK"/error list) to support feedback loops.
|
||||
</expected_outcome>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
|
||||
<example name="edit_global_skill_with_confirmation">
|
||||
<scenario>Edit an existing global skill used across multiple projects.</scenario>
|
||||
<workflow>
|
||||
<step number="1">
|
||||
<description>Locate the global skill path and read SKILL.md</description>
|
||||
<expected_outcome>Exact file to change is known</expected_outcome>
|
||||
</step>
|
||||
<step number="2">
|
||||
<description>Apply the minimal edit and re-check frontmatter constraints</description>
|
||||
<expected_outcome>Global skill updated safely and remains spec-compliant</expected_outcome>
|
||||
</step>
|
||||
</workflow>
|
||||
</example>
|
||||
</complete_examples>
|
||||
@@ -0,0 +1,17 @@
|
||||
<error_handling>
|
||||
<error_case name="name_mismatch">
|
||||
<symptom>Frontmatter name does not match directory name</symptom>
|
||||
<response>
|
||||
<step>Do not proceed with additional edits until the mismatch is resolved</step>
|
||||
<step>Prefer renaming the directory to match the intended canonical name (or update frontmatter), but confirm with the user if the skill is already in use</step>
|
||||
</response>
|
||||
</error_case>
|
||||
|
||||
<error_case name="invalid_name_format">
|
||||
<symptom>Name contains uppercase, underscores, or consecutive hyphens</symptom>
|
||||
<response>
|
||||
<step>Propose a corrected name and confirm before applying renames</step>
|
||||
<step>Explain that renames may be breaking if other tooling references the skill name</step>
|
||||
</response>
|
||||
</error_case>
|
||||
</error_handling>
|
||||
@@ -0,0 +1,15 @@
|
||||
<communication_guidelines>
|
||||
<tone_and_style>
|
||||
<principle>Be direct and technical; avoid conversational filler.</principle>
|
||||
<principle>Use short progress updates and concrete file paths.</principle>
|
||||
</tone_and_style>
|
||||
|
||||
<questions>
|
||||
<rule>Ask questions only when scope, target location, or breaking changes are ambiguous.</rule>
|
||||
<rule>When asking, provide 2–4 actionable options.</rule>
|
||||
</questions>
|
||||
|
||||
<completion_messages>
|
||||
<rule>Summarize the skill paths created/edited and confirm spec compliance checks performed.</rule>
|
||||
</completion_messages>
|
||||
</communication_guidelines>
|
||||
@@ -0,0 +1,30 @@
|
||||
<tool_guidance_guide>
|
||||
<tool_priorities>
|
||||
<priority level="1">
|
||||
<tool>List directories/files</tool>
|
||||
<when>Confirm whether skills already exist and where they should live</when>
|
||||
<why>Avoid duplicate skills and ensure correct placement (project vs global; generic vs mode-specific)</why>
|
||||
</priority>
|
||||
|
||||
<priority level="2">
|
||||
<tool>Open/read files</tool>
|
||||
<when>Inspect existing SKILL.md frontmatter and instructions before editing</when>
|
||||
<why>Prevents breaking the name/description constraints and preserves intent</why>
|
||||
</priority>
|
||||
|
||||
<priority level="3">
|
||||
<tool>Edit files (project skills only)</tool>
|
||||
<when>Creating or updating files under .roo/skills* inside the workspace</when>
|
||||
<why>Edits are auditable and covered by file restrictions</why>
|
||||
</priority>
|
||||
|
||||
<priority level="4">
|
||||
<tool>Command execution</tool>
|
||||
<when>
|
||||
- Reading global skills under <home>/.roo/skills*
|
||||
- Creating/updating global skills under <home>/.roo/skills*
|
||||
</when>
|
||||
<why>Global skills are outside the workspace; command execution is required for access</why>
|
||||
</priority>
|
||||
</tool_priorities>
|
||||
</tool_guidance_guide>
|
||||
Reference in New Issue
Block a user