feat: enhance rule file loading with .roo/rules directory support (#2354)

* feat: enhance rule file loading with .roo/rules directory support

- Introduced functions to safely read files and check for directory existence.
- Added capability to read all text files from a specified directory in alphabetical order.
- Updated `loadRuleFiles` to prioritize loading rules from a `.roo/rules/` directory, falling back to existing rule files if necessary.
- Enhanced `addCustomInstructions` to support loading mode-specific rules from a `.roo/rules-{mode}/` directory, improving flexibility in rule management.

This change improves the organization and retrieval of rule files, allowing for better modularity and maintainability.

* Updated strings and translations

* Add tests

* Revert changes to system prompt translations

* Fix path resolution

* Make instruction structure clearer

---------

Co-authored-by: Matt Rubens <[email protected]>

Author: upamune

src/core/prompts/sections/__tests__/custom-instructions.test.ts

@@ -3,6 +3,9 @@ import path from "path"
 
 import { LANGUAGES, isLanguage } from "../../../shared/language"
 
+/**
+ * Safely read a file and return its trimmed content
+ */
 async function safeReadFile(filePath: string): Promise<string> {
 	try {
 		const content = await fs.readFile(filePath, "utf-8")
@@ -16,7 +19,81 @@ async function safeReadFile(filePath: string): Promise<string> {
 	}
 }
 
+/**
+ * Check if a directory exists
+ */
+async function directoryExists(dirPath: string): Promise<boolean> {
+	try {
+		const stats = await fs.stat(dirPath)
+		return stats.isDirectory()
+	} catch (err) {
+		return false
+	}
+}
+
+/**
+ * Read all text files from a directory in alphabetical order
+ */
+async function readTextFilesFromDirectory(dirPath: string): Promise<Array<{ filename: string; content: string }>> {
+	try {
+		const files = await fs
+			.readdir(dirPath, { withFileTypes: true, recursive: true })
+			.then((files) => files.filter((file) => file.isFile()))
+			.then((files) => files.map((file) => path.resolve(dirPath, file.name)))
+
+		const fileContents = await Promise.all(
+			files.map(async (file) => {
+				try {
+					// Check if it's a file (not a directory)
+					const stats = await fs.stat(file)
+					if (stats.isFile()) {
+						const content = await safeReadFile(file)
+						return { filename: file, content }
+					}
+					return null
+				} catch (err) {
+					return null
+				}
+			}),
+		)
+
+		// Filter out null values (directories or failed reads)
+		return fileContents.filter((item): item is { filename: string; content: string } => item !== null)
+	} catch (err) {
+		return []
+	}
+}
+
+/**
+ * Format content from multiple files with filenames as headers
+ */
+function formatDirectoryContent(dirPath: string, files: Array<{ filename: string; content: string }>): string {
+	if (files.length === 0) return ""
+
+	return (
+		"\n\n" +
+		files
+			.map((file) => {
+				return `# Rules from ${file.filename}:\n${file.content}:`
+			})
+			.join("\n\n")
+	)
+}
+
+/**
+ * Load rule files from the specified directory
+ */
 export async function loadRuleFiles(cwd: string): Promise<string> {
+	// Check for .roo/rules/ directory
+	const rooRulesDir = path.join(cwd, ".roo", "rules")
+	if (await directoryExists(rooRulesDir)) {
+		const files = await readTextFilesFromDirectory(rooRulesDir)
+		if (files.length > 0) {
+			return formatDirectoryContent(rooRulesDir, files)
+		}
+	}
+
+	// Fall back to existing behavior
 	const ruleFiles = [".roorules", ".clinerules"]
 
 	for (const file of ruleFiles) {
@@ -41,16 +118,30 @@ export async function addCustomInstructions(
 	// Load mode-specific rules if mode is provided
 	let modeRuleContent = ""
 	let usedRuleFile = ""
+
 	if (mode) {
-		const rooModeRuleFile = `.roorules-${mode}`
-		modeRuleContent = await safeReadFile(path.join(cwd, rooModeRuleFile))
-		if (modeRuleContent) {
-			usedRuleFile = rooModeRuleFile
-		} else {
-			const clineModeRuleFile = `.clinerules-${mode}`
-			modeRuleContent = await safeReadFile(path.join(cwd, clineModeRuleFile))
+		// Check for .roo/rules-${mode}/ directory
+		const modeRulesDir = path.join(cwd, ".roo", `rules-${mode}`)
+		if (await directoryExists(modeRulesDir)) {
+			const files = await readTextFilesFromDirectory(modeRulesDir)
+			if (files.length > 0) {
+				modeRuleContent = formatDirectoryContent(modeRulesDir, files)
+				usedRuleFile = modeRulesDir
+			}
+		}
+
+		// If no directory exists, fall back to existing behavior
+		if (!modeRuleContent) {
+			const rooModeRuleFile = `.roorules-${mode}`
+			modeRuleContent = await safeReadFile(path.join(cwd, rooModeRuleFile))
 			if (modeRuleContent) {
-				usedRuleFile = clineModeRuleFile
+				usedRuleFile = rooModeRuleFile
+			} else {
+				const clineModeRuleFile = `.clinerules-${mode}`
+				modeRuleContent = await safeReadFile(path.join(cwd, clineModeRuleFile))
+				if (modeRuleContent) {
+					usedRuleFile = clineModeRuleFile
+				}
 			}
 		}
 	}
@@ -78,7 +169,11 @@ export async function addCustomInstructions(
 
 	// Add mode-specific rules first if they exist
 	if (modeRuleContent && modeRuleContent.trim()) {
-		rules.push(`# Rules from ${usedRuleFile}:\n${modeRuleContent}`)
+		if (usedRuleFile.includes(path.join(".roo", `rules-${mode}`))) {
+			rules.push(modeRuleContent.trim())
+		} else {
+			rules.push(`# Rules from ${usedRuleFile}:\n${modeRuleContent}`)
+		}
 	}
 
 	if (options.rooIgnoreInstructions) {

src/core/prompts/sections/custom-instructions.ts

@@ -798,7 +798,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 												// Open or create an empty file
 												vscode.postMessage({
 													type: "openFile",
-													text: `./.roorules-${currentMode.slug}`,
+													text: `./.roo/rules-${currentMode.slug}/rules.md`,
 													values: {
 														create: true,
 														content: "",
@@ -935,7 +935,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 										onClick={() =>
 											vscode.postMessage({
 												type: "openFile",
-												text: "./.roorules",
+												text: "./.roo/rules/rules.md",
 												values: {
 													create: true,
 													content: "",

webview-ui/src/components/prompts/PromptsView.tsx

@@ -36,12 +36,12 @@
 		"title": "Instruccions personalitzades específiques del mode (opcional)",
 		"resetToDefault": "Restablir a valors predeterminats",
 		"description": "Afegiu directrius de comportament específiques per al mode {{modeName}}.",
-		"loadFromFile": "Les instruccions personalitzades específiques per al mode {{mode}} també es poden carregar des de <span>.roorules-{{slug}}</span> al vostre espai de treball (.clinerules-{{slug}} està obsolet i deixarà de funcionar aviat)."
+		"loadFromFile": "Les instruccions personalitzades específiques per al mode {{mode}} també es poden carregar des de la carpeta <span>.roo/rules-{{slug}}/</span> al vostre espai de treball (.roorules-{{slug}} i .clinerules-{{slug}} estan obsolets i deixaran de funcionar aviat)."
 	},
 	"globalCustomInstructions": {
 		"title": "Instruccions personalitzades per a tots els modes",
 		"description": "Aquestes instruccions s'apliquen a tots els modes. Proporcionen un conjunt bàsic de comportaments que es poden millorar amb instruccions específiques de cada mode a continuació.\nSi voleu que Roo pensi i parli en un idioma diferent al de la visualització del vostre editor ({{language}}), podeu especificar-ho aquí.",
-		"loadFromFile": "Les instruccions també es poden carregar des de <span>.roorules</span> al vostre espai de treball (.clinerules està obsolet i deixarà de funcionar aviat)."
+		"loadFromFile": "Les instruccions també es poden carregar des de la carpeta <span>.roo/rules/</span> al vostre espai de treball (.roorules i .clinerules estan obsolets i deixaran de funcionar aviat)."
 	},
 	"systemPrompt": {
 		"preview": "Previsualització del prompt del sistema",

webview-ui/src/i18n/locales/ca/prompts.json

@@ -36,12 +36,12 @@
 		"title": "Modusspezifische benutzerdefinierte Anweisungen (optional)",
 		"resetToDefault": "Auf Standardwerte zurücksetzen",
 		"description": "Fügen Sie verhaltensspezifische Richtlinien für den Modus {{modeName}} hinzu.",
-		"loadFromFile": "Benutzerdefinierte Anweisungen für den Modus {{mode}} können auch aus <span>.roorules-{{slug}}</span> in deinem Arbeitsbereich geladen werden (.clinerules-{{slug}} ist veraltet und wird bald nicht mehr funktionieren)."
+		"loadFromFile": "Benutzerdefinierte Anweisungen für den Modus {{mode}} können auch aus dem Ordner <span>.roo/rules-{{slug}}/</span> in deinem Arbeitsbereich geladen werden (.roorules-{{slug}} und .clinerules-{{slug}} sind veraltet und werden bald nicht mehr funktionieren)."
 	},
 	"globalCustomInstructions": {
 		"title": "Benutzerdefinierte Anweisungen für alle Modi",
 		"description": "Diese Anweisungen gelten für alle Modi. Sie bieten einen grundlegenden Satz von Verhaltensweisen, die durch modusspezifische Anweisungen unten erweitert werden können.\nWenn du möchtest, dass Roo in einer anderen Sprache als deiner Editor-Anzeigesprache ({{language}}) denkt und spricht, kannst du das hier angeben.",
-		"loadFromFile": "Anweisungen können auch aus <span>.roorules</span> in deinem Arbeitsbereich geladen werden (.clinerules ist veraltet und wird bald nicht mehr funktionieren)."
+		"loadFromFile": "Anweisungen können auch aus dem Ordner <span>.roo/rules/</span> in deinem Arbeitsbereich geladen werden (.roorules und .clinerules sind veraltet und werden bald nicht mehr funktionieren)."
 	},
 	"systemPrompt": {
 		"preview": "System-Prompt Vorschau",

webview-ui/src/i18n/locales/de/prompts.json

@@ -36,12 +36,12 @@
 		"title": "Mode-specific Custom Instructions (optional)",
 		"resetToDefault": "Reset to default",
 		"description": "Add behavioral guidelines specific to {{modeName}} mode.",
-		"loadFromFile": "Custom instructions specific to {{mode}} mode can also be loaded from <span>.roorules-{{slug}}</span> in your workspace (.clinerules-{{slug}} is deprecated and will stop working soon)."
+		"loadFromFile": "Custom instructions specific to {{mode}} mode can also be loaded from the <span>.roo/rules-{{slug}}/</span> folder in your workspace (.roorules-{{slug}} and .clinerules-{{slug}} are deprecated and will stop working soon)."
 	},
 	"globalCustomInstructions": {
 		"title": "Custom Instructions for All Modes",
 		"description": "These instructions apply to all modes. They provide a base set of behaviors that can be enhanced by mode-specific instructions below.\nIf you would like Roo to think and speak in a different language than your editor display language ({{language}}), you can specify it here.",
-		"loadFromFile": "Instructions can also be loaded from <span>.roorules</span> in your workspace (.clinerules is deprecated and will stop working soon)."
+		"loadFromFile": "Instructions can also be loaded from the <span>.roo/rules/</span> folder in your workspace (.roorules and .clinerules are deprecated and will stop working soon)."
 	},
 	"systemPrompt": {
 		"preview": "Preview System Prompt",

webview-ui/src/i18n/locales/en/prompts.json

@@ -36,12 +36,12 @@
 		"title": "Instrucciones personalizadas para el modo (opcional)",
 		"resetToDefault": "Restablecer a valores predeterminados",
 		"description": "Agrega directrices de comportamiento específicas para el modo {{modeName}}.",
-		"loadFromFile": "Las instrucciones personalizadas para el modo {{mode}} también se pueden cargar desde <span>.roorules-{{slug}}</span> en tu espacio de trabajo (.clinerules-{{slug}} está obsoleto y dejará de funcionar pronto)."
+		"loadFromFile": "Las instrucciones personalizadas para el modo {{mode}} también se pueden cargar desde la carpeta <span>.roo/rules-{{slug}}/</span> en tu espacio de trabajo (.roorules-{{slug}} y .clinerules-{{slug}} están obsoletos y dejarán de funcionar pronto)."
 	},
 	"globalCustomInstructions": {
 		"title": "Instrucciones personalizadas para todos los modos",
 		"description": "Estas instrucciones se aplican a todos los modos. Proporcionan un conjunto base de comportamientos que pueden ser mejorados por instrucciones específicas de cada modo.\nSi quieres que Roo piense y hable en un idioma diferente al idioma de visualización de tu editor ({{language}}), puedes especificarlo aquí.",
-		"loadFromFile": "Las instrucciones también se pueden cargar desde <span>.roorules</span> en tu espacio de trabajo (.clinerules está obsoleto y dejará de funcionar pronto)."
+		"loadFromFile": "Las instrucciones también se pueden cargar desde la carpeta <span>.roo/rules/</span> en tu espacio de trabajo (.roorules y .clinerules están obsoletos y dejarán de funcionar pronto)."
 	},
 	"systemPrompt": {
 		"preview": "Vista previa de la solicitud del sistema",

webview-ui/src/i18n/locales/es/prompts.json

@@ -36,12 +36,12 @@
 		"title": "Instructions personnalisées spécifiques au mode (optionnel)",
 		"resetToDefault": "Réinitialiser aux valeurs par défaut",
 		"description": "Ajoutez des directives comportementales spécifiques au mode {{modeName}}.",
-		"loadFromFile": "Les instructions personnalisées spécifiques au mode {{mode}} peuvent également être chargées depuis <span>.roorules-{{slug}}</span> dans votre espace de travail (.clinerules-{{slug}} est obsolète et cessera de fonctionner bientôt)."
+		"loadFromFile": "Les instructions personnalisées spécifiques au mode {{mode}} peuvent également être chargées depuis le dossier <span>.roo/rules-{{slug}}/</span> dans votre espace de travail (.roorules-{{slug}} et .clinerules-{{slug}} sont obsolètes et cesseront de fonctionner bientôt)."
 	},
 	"globalCustomInstructions": {
 		"title": "Instructions personnalisées pour tous les modes",
 		"description": "Ces instructions s'appliquent à tous les modes. Elles fournissent un ensemble de comportements de base qui peuvent être améliorés par des instructions spécifiques au mode ci-dessous.\nSi vous souhaitez que Roo pense et parle dans une langue différente de celle de votre éditeur ({{language}}), vous pouvez le spécifier ici.",
-		"loadFromFile": "Les instructions peuvent également être chargées depuis <span>.roorules</span> dans votre espace de travail (.clinerules est obsolète et cessera de fonctionner bientôt)."
+		"loadFromFile": "Les instructions peuvent également être chargées depuis le dossier <span>.roo/rules/</span> dans votre espace de travail (.roorules et .clinerules sont obsolètes et cesseront de fonctionner bientôt)."
 	},
 	"systemPrompt": {
 		"preview": "Aperçu du prompt système",

webview-ui/src/i18n/locales/fr/prompts.json

@@ -36,12 +36,12 @@
 		"title": "मोड-विशिष्ट कस्टम निर्देश (वैकल्पिक)",
 		"resetToDefault": "डिफ़ॉल्ट पर रीसेट करें",
 		"description": "{{modeName}} मोड के लिए विशिष्ट व्यवहार दिशानिर्देश जोड़ें।",
-		"loadFromFile": "{{mode}} मोड के लिए विशिष्ट कस्टम निर्देश आपके वर्कस्पेस में <span>.roorules-{{slug}}</span> से भी लोड किए जा सकते हैं (.clinerules-{{slug}} पुराना हो गया है और जल्द ही काम करना बंद कर देगा)।"
+		"loadFromFile": "{{mode}} मोड के लिए विशिष्ट कस्टम निर्देश आपके वर्कस्पेस में <span>.roo/rules-{{slug}}/</span> फ़ोल्डर से भी लोड किए जा सकते हैं (.roorules-{{slug}} और .clinerules-{{slug}} पुराने हो गए हैं और जल्द ही काम करना बंद कर देंगे)।"
 	},
 	"globalCustomInstructions": {
 		"title": "सभी मोड्स के लिए कस्टम निर्देश",
 		"description": "ये निर्देश सभी मोड्स पर लागू होते हैं। वे व्यवहारों का एक आधार सेट प्रदान करते हैं जिन्हें नीचे दिए गए मोड-विशिष्ट निर्देशों द्वारा बढ़ाया जा सकता है।\nयदि आप चाहते हैं कि Roo आपके एडिटर की प्रदर्शन भाषा ({{language}}) से अलग भाषा में सोचे और बोले, तो आप यहां इसे निर्दिष्ट कर सकते हैं।",
-		"loadFromFile": "निर्देश आपके वर्कस्पेस में <span>.roorules</span> से भी लोड किए जा सकते हैं (.clinerules पुराना हो गया है और जल्द ही काम करना बंद कर देगा)।"
+		"loadFromFile": "निर्देश आपके वर्कस्पेस में <span>.roo/rules/</span> फ़ोल्डर से भी लोड किए जा सकते हैं (.roorules और .clinerules पुराने हो गए हैं और जल्द ही काम करना बंद कर देंगे)।"
 	},
 	"systemPrompt": {
 		"preview": "सिस्टम प्रॉम्प्ट का पूर्वावलोकन",

webview-ui/src/i18n/locales/hi/prompts.json

@@ -36,12 +36,12 @@
 		"title": "Istruzioni personalizzate specifiche per la modalità (opzionale)",
 		"resetToDefault": "Ripristina predefiniti",
 		"description": "Aggiungi linee guida comportamentali specifiche per la modalità {{modeName}}.",
-		"loadFromFile": "Le istruzioni personalizzate specifiche per la modalità {{mode}} possono essere caricate anche da <span>.roorules-{{slug}}</span> nel tuo spazio di lavoro (.clinerules-{{slug}} è obsoleto e smetterà di funzionare presto)."
+		"loadFromFile": "Le istruzioni personalizzate specifiche per la modalità {{mode}} possono essere caricate anche dalla cartella <span>.roo/rules-{{slug}}/</span> nel tuo spazio di lavoro (.roorules-{{slug}} e .clinerules-{{slug}} sono obsoleti e smetteranno di funzionare presto)."
 	},
 	"globalCustomInstructions": {
 		"title": "Istruzioni personalizzate per tutte le modalità",
 		"description": "Queste istruzioni si applicano a tutte le modalità. Forniscono un insieme base di comportamenti che possono essere migliorati dalle istruzioni specifiche per modalità qui sotto.\nSe desideri che Roo pensi e parli in una lingua diversa dalla lingua di visualizzazione del tuo editor ({{language}}), puoi specificarlo qui.",
-		"loadFromFile": "Le istruzioni possono essere caricate anche da <span>.roorules</span> nel tuo spazio di lavoro (.clinerules è obsoleto e smetterà di funzionare presto)."
+		"loadFromFile": "Le istruzioni possono essere caricate anche dalla cartella <span>.roo/rules/</span> nel tuo spazio di lavoro (.roorules e .clinerules sono obsoleti e smetteranno di funzionare presto)."
 	},
 	"systemPrompt": {
 		"preview": "Anteprima prompt di sistema",