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