Improve mode prompting with dynamic custom instructions loading

[Mnehmos]

What problem does this proposed feature solve?

This PR implements dynamic loading of custom mode prompts from different sources with a clear priority hierarchy:

1. Project-level files in .roo/prompts
2. User-specific settings (highest priority)
3. Built-in defaults (lowest priority)

It also standardizes how we inject these prompts into Roo.

Related to our discussions about making the prompt engineering workflow more intuitive.

/cc @hannes

Describe the proposed solution in detail

Dynamic Mode Prompting for Roo: Detailed Solution
Overview
The proposed solution implements a hierarchical, file-based system for loading and managing mode-specific prompts in Roo. This creates a more flexible and maintainable approach to customizing Roo's behavior across different operational modes.
Key Components

1. Multi-Source Prompt Loading with Clear Hierarchy
   Implement a priority-based system for resolving custom instructions:

User-specific settings (highest priority)
Project-level files in .roo/prompts/ directory
Built-in defaults (lowest priority)

2. Enhanced Prompt Result Structure
   Refactor addCustomInstructions to return a comprehensive CustomInstructionsResult object containing:

finalRoleDefinition: The resolved role definition
finalWhenToUse: Usage guidelines for the mode
assembledCustomInstructions: The full assembled custom instructions
finalLanguage: Language preference
Information about global instructions and their source

3. File-Based Prompt Organization
   Support loading from structured files in the project:

Mode-specific definitions from .roo/prompts/modes/${mode}.md
Global prompts from .roo/prompts/global.md
Mode-agnostic rules from .roo/prompts/all_modes.md

4. Standard Format for Mode Files
   Mode files can include sections for:

Role Definition: Core identity of the mode
When to Use: Guidance on appropriate usage scenarios
Custom Instructions: Mode-specific behavior instructions

5. Updated Mode Configuration Structure
   Modify ModeConfig to:

Make roleDefinition optional (can be loaded from files)
Add a dedicated whenToUse field
Support proper fallback behavior when configurations are missing

6. UI Transparency Enhancements
   Add UI elements that show users the source of active instructions:

Indicators for instructions from user settings
Indicators for instructions from project files
Indicators when using built-in defaults

7. Standardized Mode Resolution Flow
   Implement a consistent process for mode resolution across the application:

Robust error handling with appropriate fallbacks
Clear logging for troubleshooting
Support for custom modes while maintaining backward compatibility

Benefits

Better Project-Level Customization: Teams can version-control mode configurations
Clearer User Experience: Users understand where instructions come from
Foundation for Mode Marketplace: Standardized format enables sharing and distribution of modes
Flexibility: Different prompting strategies for different projects
Maintainability: Separate mode definitions from code

Technical Implementation
The solution maintains backward compatibility while introducing the new file-based approach, with careful updating of all dependent code paths to use the enhanced CustomInstructionsResult interface.

Technical considerations or implementation details (optional)

echnical Implementation Details for Dynamic Mode Prompting
Core Architecture Changes

1. Enhanced Return Type for Custom Instructions
   typescriptexport interface CustomInstructionsResult {
   finalRoleDefinition: string
   finalWhenToUse: string
   assembledCustomInstructions: string
   finalLanguage: Language | undefined
   finalRooIgnoreInstructions?: string
   activeGlobalCustomInstructions: string
   globalInstructionsSource: GlobalInstructionSource
   }
   This structured return type replaces the previous string-only return, enabling better tracking of where each component originated.
2. File System Organization
   .roo/
   ├── prompts/
   │ ├── global.md # Global instructions for all modes
   │ ├── all_modes.md # Rules applied to all modes
   │ └── modes/
   │ ├── code.md # Mode-specific definition
   │ ├── architect.md # Mode-specific definition
   │ └── ask.md # Mode-specific definition
3. Mode File Format
   Mode files should use Markdown with specific sections:
   markdown## Role Definition
   You are Roo, a proficient Software Engineer...

When to Use

For writing, modifying, testing, and documenting source code...

Custom Instructions

As a Code specialist:

1. SPARC for Development: Apply Observe, Define, Infer...
2. Instruction Source Hierarchy
   typescript// Priority implementation
   if (globalCustomInstructionsFromSettings && globalCustomInstructionsFromSettings.trim() !== "") {
   determinedGlobalCustomInstructions = globalCustomInstructionsFromSettings;
   determinedGlobalInstructionsSource = 'user_settings';
   } else if (fileGlobalCustomInstructions && fileGlobalCustomInstructions.trim() !== "") {
   determinedGlobalCustomInstructions = fileGlobalCustomInstructions;
   determinedGlobalInstructionsSource = 'project_file';
   } else if (DEFAULT_GLOBAL_CUSTOM_INSTRUCTIONS && DEFAULT_GLOBAL_CUSTOM_INSTRUCTIONS.trim() !== "") {
   determinedGlobalCustomInstructions = DEFAULT_GLOBAL_CUSTOM_INSTRUCTIONS;
   determinedGlobalInstructionsSource = 'default';
   }
   Technical Considerations
3. Backward Compatibility

Make roleDefinition optional in ModeConfig schema
Maintain support for existing customModes structure
Ensure default fallbacks work without file-based prompts

2. Error Handling & Resilience

Implement graceful fallbacks when files don't exist
Add clear error messages when modes can't be resolved
Prevent UI crashes with defensive null checks

3. Performance Optimization

Cache resolved modes to prevent redundant file operations
Use lazy loading where appropriate
Implement efficient file parsing with minimal string operations

4. Testing Strategy

Unit tests for file parsing logic
Integration tests for prompt resolution
Snapshot tests to verify assembled instructions
Mock file system operations for predictable test results

5. Extension State Management

Update state to include instruction source information
Add UI components to display source information
Ensure settings synchronization across components

6. File Content Security

Sanitize file content to prevent injection attacks
Validate file content against expected format
Set reasonable size limits for custom instruction files

7. Dependencies and APIs

Consistent use of Node.js path APIs for cross-platform compatibility
Robust file system error handling with typed exceptions
Clear logging for debugging file loading issues

8. Feature Discoverability

Add documentation on file format in the .roo directory
Provide UI indicators showing where instructions are loaded from
Include example template files for different modes

These technical considerations ensure the implementation is robust, maintainable, and provides a solid foundation for future mode marketplace functionality.

Describe alternatives considered (if any)

No response

Additional Context & Mockups

No response

Proposal Checklist

• I have searched existing Issues and Discussions to ensure this proposal is not a duplicate.
• This proposal is for a specific, actionable change intended for implementation (not a general idea).
• I understand that this proposal requires review and approval before any development work begins.

Are you interested in implementing this feature if approved?

• Yes, I would like to contribute to implementing this feature.

[hannesrudolph]

@mrubens @mrubens Thoughts on this?

[R-omk]

Related #3749 (comment)

[R-omk]

UI Transparency Enhancements

Some small related (on the fly prompt) #3903

[hannesrudolph]

@hannesrudolph I am not sure what problem this solves. Please modify your original post.