Add a 'when to use' section to mode definitions (#3571)

* Add a 'when to use' section to mode definitions

* Remove defaults for now

.changeset/dark-swans-marry.md

@@ -0,0 +1,5 @@
+---
+"roo-cline": patch
+---
+
+Add a 'when to use' section to mode definitions

src/core/prompts/instructions/create-mode.ts

@@ -25,7 +25,9 @@ If asked to create a project mode, create it in .roomodes in the workspace root.
   * roleDefinition: A detailed description of the mode's role and capabilities
   * groups: Array of allowed tool groups (can be empty). Each group can be specified either as a string (e.g., "edit" to allow editing any file) or with file restrictions (e.g., ["edit", { fileRegex: "\\.md$", description: "Markdown files only" }] to only allow editing markdown files)
 
-- The customInstructions field is optional.
+- The following fields are optional but highly recommended:
+  * whenToUse: A clear description of when this mode should be selected and what types of tasks it's best suited for. This helps the Orchestrator mode make better decisions.
+  * customInstructions: Additional instructions for how the mode should operate
 
 - For multi-line text, include newline characters in the string like "This is the first line.\\nThis is the next line.\\n\\nThis is a double line break."
 
@@ -36,6 +38,7 @@ Both files should follow this structure:
      "slug": "designer", // Required: unique slug with lowercase letters, numbers, and hyphens
      "name": "Designer", // Required: mode display name
      "roleDefinition": "You are Roo, a UI/UX expert specializing in design systems and frontend development. Your expertise includes:\\n- Creating and maintaining design systems\\n- Implementing responsive and accessible web interfaces\\n- Working with CSS, HTML, and modern frontend frameworks\\n- Ensuring consistent user experiences across platforms", // Required: non-empty
+     "whenToUse": "Use this mode when creating or modifying UI components, implementing design systems, or ensuring responsive web interfaces. This mode is especially effective with CSS, HTML, and modern frontend frameworks.", // Optional but recommended
      "groups": [ // Required: array of tool groups (can be empty)
        "read",    // Read files group (read_file, fetch_instructions, search_files, list_files, list_code_definition_names)
        "edit",    // Edit files group (apply_diff, write_to_file) - allows editing any file

src/core/prompts/sections/modes.ts

@@ -16,7 +16,19 @@ export async function getModesSection(context: vscode.ExtensionContext): Promise
 MODES
 
 - These are the currently available modes:
-${allModes.map((mode: ModeConfig) => `  * "${mode.name}" mode (${mode.slug}) - ${mode.roleDefinition.split(".")[0]}`).join("\n")}`
+${allModes
+	.map((mode: ModeConfig) => {
+		let description: string
+		if (mode.whenToUse && mode.whenToUse.trim() !== "") {
+			// Use whenToUse as the primary description, indenting subsequent lines for readability
+			description = mode.whenToUse.replace(/\n/g, "\n    ")
+		} else {
+			// Fallback to the first sentence of roleDefinition if whenToUse is not available
+			description = mode.roleDefinition.split(".")[0]
+		}
+		return `  * "${mode.name}" mode (${mode.slug}) - ${description}`
+	})
+	.join("\n")}`
 
 	modesContent += `
 If the user asks you to create or edit a new mode for this project, you should read the instructions by using the fetch_instructions tool, like this:

src/exports/roo-code.d.ts

@@ -138,6 +138,7 @@ type GlobalSettings = {
 				slug: string
 				name: string
 				roleDefinition: string
+				whenToUse?: string | undefined
 				customInstructions?: string | undefined
 				groups: (
 					| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -157,6 +158,7 @@ type GlobalSettings = {
 				[x: string]:
 					| {
 							roleDefinition?: string | undefined
+							whenToUse?: string | undefined
 							customInstructions?: string | undefined
 					  }
 					| undefined
@@ -822,6 +824,7 @@ type IpcMessage =
 											slug: string
 											name: string
 											roleDefinition: string
+											whenToUse?: string | undefined
 											customInstructions?: string | undefined
 											groups: (
 												| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -841,6 +844,7 @@ type IpcMessage =
 											[x: string]:
 												| {
 														roleDefinition?: string | undefined
+														whenToUse?: string | undefined
 														customInstructions?: string | undefined
 												  }
 												| undefined
@@ -1282,6 +1286,7 @@ type TaskCommand =
 								slug: string
 								name: string
 								roleDefinition: string
+								whenToUse?: string | undefined
 								customInstructions?: string | undefined
 								groups: (
 									| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -1301,6 +1306,7 @@ type TaskCommand =
 								[x: string]:
 									| {
 											roleDefinition?: string | undefined
+											whenToUse?: string | undefined
 											customInstructions?: string | undefined
 									  }
 									| undefined

src/exports/types.ts

@@ -138,6 +138,7 @@ type GlobalSettings = {
 				slug: string
 				name: string
 				roleDefinition: string
+				whenToUse?: string | undefined
 				customInstructions?: string | undefined
 				groups: (
 					| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -157,6 +158,7 @@ type GlobalSettings = {
 				[x: string]:
 					| {
 							roleDefinition?: string | undefined
+							whenToUse?: string | undefined
 							customInstructions?: string | undefined
 					  }
 					| undefined
@@ -834,6 +836,7 @@ type IpcMessage =
 											slug: string
 											name: string
 											roleDefinition: string
+											whenToUse?: string | undefined
 											customInstructions?: string | undefined
 											groups: (
 												| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -853,6 +856,7 @@ type IpcMessage =
 											[x: string]:
 												| {
 														roleDefinition?: string | undefined
+														whenToUse?: string | undefined
 														customInstructions?: string | undefined
 												  }
 												| undefined
@@ -1296,6 +1300,7 @@ type TaskCommand =
 								slug: string
 								name: string
 								roleDefinition: string
+								whenToUse?: string | undefined
 								customInstructions?: string | undefined
 								groups: (
 									| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -1315,6 +1320,7 @@ type TaskCommand =
 								[x: string]:
 									| {
 											roleDefinition?: string | undefined
+											whenToUse?: string | undefined
 											customInstructions?: string | undefined
 									  }
 									| undefined

src/schemas/index.ts

@@ -217,6 +217,7 @@ export const modeConfigSchema = z.object({
 	slug: z.string().regex(/^[a-zA-Z0-9-]+$/, "Slug must contain only letters numbers and dashes"),
 	name: z.string().min(1, "Name is required"),
 	roleDefinition: z.string().min(1, "Role definition is required"),
+	whenToUse: z.string().optional(),
 	customInstructions: z.string().optional(),
 	groups: groupEntryArraySchema,
 	source: z.enum(["global", "project"]).optional(),
@@ -256,6 +257,7 @@ export type CustomModesSettings = z.infer<typeof customModesSettingsSchema>
 
 export const promptComponentSchema = z.object({
 	roleDefinition: z.string().optional(),
+	whenToUse: z.string().optional(),
 	customInstructions: z.string().optional(),
 })
 

src/shared/modes.ts

@@ -233,6 +233,7 @@ export const defaultPrompts: Readonly<CustomModePrompts> = Object.freeze(
 			mode.slug,
 			{
 				roleDefinition: mode.roleDefinition,
+				whenToUse: mode.whenToUse,
 				customInstructions: mode.customInstructions,
 			},
 		]),
@@ -248,6 +249,7 @@ export async function getAllModesWithPrompts(context: vscode.ExtensionContext):
 	return allModes.map((mode) => ({
 		...mode,
 		roleDefinition: customModePrompts[mode.slug]?.roleDefinition ?? mode.roleDefinition,
+		whenToUse: customModePrompts[mode.slug]?.whenToUse ?? mode.whenToUse,
 		customInstructions: customModePrompts[mode.slug]?.customInstructions ?? mode.customInstructions,
 	}))
 }
@@ -271,6 +273,7 @@ export async function getFullModeDetails(
 
 	// Get the base custom instructions
 	const baseCustomInstructions = promptComponent?.customInstructions || baseMode.customInstructions || ""
+	const baseWhenToUse = promptComponent?.whenToUse || baseMode.whenToUse || ""
 
 	// If we have cwd, load and combine all custom instructions
 	let fullCustomInstructions = baseCustomInstructions
@@ -288,6 +291,7 @@ export async function getFullModeDetails(
 	return {
 		...baseMode,
 		roleDefinition: promptComponent?.roleDefinition || baseMode.roleDefinition,
+		whenToUse: baseWhenToUse,
 		customInstructions: fullCustomInstructions,
 	}
 }
@@ -302,6 +306,16 @@ export function getRoleDefinition(modeSlug: string, customModes?: ModeConfig[]):
 	return mode.roleDefinition
 }
 
+// Helper function to safely get whenToUse
+export function getWhenToUse(modeSlug: string, customModes?: ModeConfig[]): string {
+	const mode = getModeBySlug(modeSlug, customModes)
+	if (!mode) {
+		console.warn(`No mode found for slug: ${modeSlug}`)
+		return ""
+	}
+	return mode.whenToUse ?? ""
+}
+
 // Helper function to safely get custom instructions
 export function getCustomInstructions(modeSlug: string, customModes?: ModeConfig[]): string {
 	const mode = getModeBySlug(modeSlug, customModes)

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

@@ -7,6 +7,7 @@ import {
 	Mode,
 	PromptComponent,
 	getRoleDefinition,
+	getWhenToUse,
 	getCustomInstructions,
 	getAllModes,
 	ModeConfig,
@@ -106,6 +107,9 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 			if (updatedPrompt.roleDefinition === getRoleDefinition(mode)) {
 				delete updatedPrompt.roleDefinition
 			}
+			if (updatedPrompt.whenToUse === getWhenToUse(mode)) {
+				delete updatedPrompt.whenToUse
+			}
 
 			vscode.postMessage({
 				type: "updatePrompt",
@@ -195,6 +199,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 	const [newModeName, setNewModeName] = useState("")
 	const [newModeSlug, setNewModeSlug] = useState("")
 	const [newModeRoleDefinition, setNewModeRoleDefinition] = useState("")
+	const [newModeWhenToUse, setNewModeWhenToUse] = useState("")
 	const [newModeCustomInstructions, setNewModeCustomInstructions] = useState("")
 	const [newModeGroups, setNewModeGroups] = useState<GroupEntry[]>(availableGroups)
 	const [newModeSource, setNewModeSource] = useState<ModeSource>("global")
@@ -212,6 +217,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 		setNewModeSlug("")
 		setNewModeGroups(availableGroups)
 		setNewModeRoleDefinition("")
+		setNewModeWhenToUse("")
 		setNewModeCustomInstructions("")
 		setNewModeSource("global")
 		// Reset error states
@@ -258,6 +264,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 			slug: newModeSlug,
 			name: newModeName,
 			roleDefinition: newModeRoleDefinition.trim(),
+			whenToUse: newModeWhenToUse.trim() || undefined,
 			customInstructions: newModeCustomInstructions.trim() || undefined,
 			groups: newModeGroups,
 			source,
@@ -299,6 +306,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 		newModeName,
 		newModeSlug,
 		newModeRoleDefinition,
+		newModeWhenToUse, // Add whenToUse dependency
 		newModeCustomInstructions,
 		newModeGroups,
 		newModeSource,
@@ -396,7 +404,7 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 		})
 	}
 
-	const handleAgentReset = (modeSlug: string, type: "roleDefinition" | "customInstructions") => {
+	const handleAgentReset = (modeSlug: string, type: "roleDefinition" | "whenToUse" | "customInstructions") => {
 		// Only reset for built-in modes
 		const existingPrompt = customModePrompts?.[modeSlug] as PromptComponent
 		const updatedPrompt = { ...existingPrompt }
@@ -699,6 +707,61 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 							data-testid={`${getCurrentMode()?.slug || "code"}-prompt-textarea`}
 						/>
 					</div>
+
+					{/* When to Use section */}
+					<div className="mb-4">
+						<div className="flex justify-between items-center mb-1">
+							<div className="font-bold">{t("prompts:whenToUse.title")}</div>
+							{!findModeBySlug(visualMode, customModes) && (
+								<Button
+									variant="ghost"
+									size="icon"
+									onClick={() => {
+										const currentMode = getCurrentMode()
+										if (currentMode?.slug) {
+											handleAgentReset(currentMode.slug, "whenToUse")
+										}
+									}}
+									title={t("prompts:whenToUse.resetToDefault")}
+									data-testid="when-to-use-reset">
+									<span className="codicon codicon-discard"></span>
+								</Button>
+							)}
+						</div>
+						<div className="text-sm text-vscode-descriptionForeground mb-2">
+							{t("prompts:whenToUse.description")}
+						</div>
+						<VSCodeTextArea
+							value={(() => {
+								const customMode = findModeBySlug(visualMode, customModes)
+								const prompt = customModePrompts?.[visualMode] as PromptComponent
+								return customMode?.whenToUse ?? prompt?.whenToUse ?? getWhenToUse(visualMode)
+							})()}
+							onChange={(e) => {
+								const value =
+									(e as unknown as CustomEvent)?.detail?.target?.value ||
+									((e as any).target as HTMLTextAreaElement).value
+								const customMode = findModeBySlug(visualMode, customModes)
+								if (customMode) {
+									// For custom modes, update the JSON file
+									updateCustomMode(visualMode, {
+										...customMode,
+										whenToUse: value.trim() || undefined,
+										source: customMode.source || "global",
+									})
+								} else {
+									// For built-in modes, update the prompts
+									updateAgentPrompt(visualMode, {
+										whenToUse: value.trim() || undefined,
+									})
+								}
+							}}
+							className="resize-y w-full"
+							rows={3}
+							data-testid={`${getCurrentMode()?.slug || "code"}-when-to-use-textarea`}
+						/>
+					</div>
+
 					{/* Mode settings */}
 					<>
 						<div className="mb-3">
@@ -1258,6 +1321,21 @@ const PromptsView = ({ onDone }: PromptsViewProps) => {
 									</div>
 								)}
 							</div>
+
+							<div className="mb-4">
+								<div className="font-bold mb-1">{t("prompts:createModeDialog.whenToUse.label")}</div>
+								<div className="text-[13px] text-vscode-descriptionForeground mb-2">
+									{t("prompts:createModeDialog.whenToUse.description")}
+								</div>
+								<VSCodeTextArea
+									value={newModeWhenToUse}
+									onChange={(e) => {
+										setNewModeWhenToUse((e.target as HTMLTextAreaElement).value)
+									}}
+									rows={3}
+									className="w-full resize-y"
+								/>
+							</div>
 							<div className="mb-4">
 								<div className="font-bold mb-1">{t("prompts:createModeDialog.tools.label")}</div>
 								<div className="text-[13px] text-vscode-descriptionForeground mb-2">

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Restablir a valors predeterminats",
 		"description": "Definiu l'experiència i personalitat de Roo per a aquest mode. Aquesta descripció determina com Roo es presenta i aborda les tasques."
 	},
+	"whenToUse": {
+		"title": "Quan utilitzar (opcional)",
+		"description": "Descriviu quan s'hauria d'utilitzar aquest mode. Això ajuda l'Orchestrator a escollir el mode correcte per a una tasca.",
+		"resetToDefault": "Restablir la descripció 'Quan utilitzar' a valors predeterminats"
+	},
 	"customInstructions": {
 		"title": "Instruccions personalitzades específiques del mode (opcional)",
 		"resetToDefault": "Restablir a valors predeterminats",
@@ -131,6 +136,10 @@
 			"label": "Definició de rol",
 			"description": "Definiu l'experiència i personalitat de Roo per a aquest mode."
 		},
+		"whenToUse": {
+			"label": "Quan utilitzar (opcional)",
+			"description": "Proporcioneu una descripció clara de quan aquest mode és més efectiu i per a quins tipus de tasques excel·leix."
+		},
 		"tools": {
 			"label": "Eines disponibles",
 			"description": "Seleccioneu quines eines pot utilitzar aquest mode."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Auf Standardwerte zurücksetzen",
 		"description": "Definiere Roos Expertise und Persönlichkeit für diesen Modus. Diese Beschreibung prägt, wie Roo sich präsentiert und an Aufgaben herangeht."
 	},
+	"whenToUse": {
+		"title": "Wann zu verwenden (optional)",
+		"description": "Beschreibe, wann dieser Modus verwendet werden sollte. Dies hilft dem Orchestrator, den richtigen Modus für eine Aufgabe auszuwählen.",
+		"resetToDefault": "Beschreibung 'Wann zu verwenden' auf Standardwerte zurücksetzen"
+	},
 	"customInstructions": {
 		"title": "Modusspezifische benutzerdefinierte Anweisungen (optional)",
 		"resetToDefault": "Auf Standardwerte zurücksetzen",
@@ -131,6 +136,10 @@
 			"label": "Rollendefinition",
 			"description": "Definiere Roos Expertise und Persönlichkeit für diesen Modus."
 		},
+		"whenToUse": {
+			"label": "Wann zu verwenden (optional)",
+			"description": "Gib eine klare Beschreibung, wann dieser Modus am effektivsten ist und für welche Arten von Aufgaben er sich besonders eignet."
+		},
 		"tools": {
 			"label": "Verfügbare Werkzeuge",
 			"description": "Wähle, welche Werkzeuge dieser Modus verwenden kann."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Reset to default",
 		"description": "Define Roo's expertise and personality for this mode. This description shapes how Roo presents itself and approaches tasks."
 	},
+	"whenToUse": {
+		"title": "When to Use (optional)",
+		"description": "Describe when this mode should be used. This helps the Orchestrator choose the right mode for a task.",
+		"resetToDefault": "Reset to default 'When to Use' description"
+	},
 	"customInstructions": {
 		"title": "Mode-specific Custom Instructions (optional)",
 		"resetToDefault": "Reset to default",
@@ -131,6 +136,10 @@
 			"label": "Role Definition",
 			"description": "Define Roo's expertise and personality for this mode."
 		},
+		"whenToUse": {
+			"label": "When to Use (optional)",
+			"description": "Provide a clear description of when this mode is most effective and what types of tasks it excels at."
+		},
 		"tools": {
 			"label": "Available Tools",
 			"description": "Select which tools this mode can use."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Restablecer a valores predeterminados",
 		"description": "Define la experiencia y personalidad de Roo para este modo. Esta descripción determina cómo Roo se presenta y aborda las tareas."
 	},
+	"whenToUse": {
+		"title": "Cuándo usar (opcional)",
+		"description": "Describe cuándo se debe usar este modo. Esto ayuda al Orchestrator a elegir el modo correcto para una tarea.",
+		"resetToDefault": "Restablecer a valores predeterminados la descripción 'Cuándo usar'"
+	},
 	"customInstructions": {
 		"title": "Instrucciones personalizadas para el modo (opcional)",
 		"resetToDefault": "Restablecer a valores predeterminados",
@@ -131,6 +136,10 @@
 			"label": "Definición de rol",
 			"description": "Define la experiencia y personalidad de Roo para este modo."
 		},
+		"whenToUse": {
+			"label": "Cuándo usar (opcional)",
+			"description": "Proporciona una descripción clara de cuándo este modo es más efectivo y para qué tipos de tareas es más adecuado."
+		},
 		"tools": {
 			"label": "Herramientas disponibles",
 			"description": "Selecciona qué herramientas puede usar este modo."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Réinitialiser aux valeurs par défaut",
 		"description": "Définissez l'expertise et la personnalité de Roo pour ce mode. Cette description façonne la manière dont Roo se présente et aborde les tâches."
 	},
+	"whenToUse": {
+		"title": "Quand utiliser (optionnel)",
+		"description": "Décrivez quand ce mode doit être utilisé. Cela aide l'Orchestrateur à choisir le mode approprié pour une tâche.",
+		"resetToDefault": "Réinitialiser la description 'Quand utiliser' aux valeurs par défaut"
+	},
 	"customInstructions": {
 		"title": "Instructions personnalisées spécifiques au mode (optionnel)",
 		"resetToDefault": "Réinitialiser aux valeurs par défaut",
@@ -131,6 +136,10 @@
 			"label": "Définition du rôle",
 			"description": "Définissez l'expertise et la personnalité de Roo pour ce mode."
 		},
+		"whenToUse": {
+			"label": "Quand utiliser (optionnel)",
+			"description": "Fournissez une description claire de quand ce mode est le plus efficace et pour quels types de tâches il excelle."
+		},
 		"tools": {
 			"label": "Outils disponibles",
 			"description": "Sélectionnez quels outils ce mode peut utiliser."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "डिफ़ॉल्ट पर रीसेट करें",
 		"description": "इस मोड के लिए Roo की विशेषज्ञता और व्यक्तित्व परिभाषित करें। यह विवरण Roo के स्वयं को प्रस्तुत करने और कार्यों से निपटने के तरीके को आकार देता है।"
 	},
+	"whenToUse": {
+		"title": "कब उपयोग करें (वैकल्पिक)",
+		"description": "बताएं कि इस मोड का उपयोग कब किया जाना चाहिए। यह Orchestrator को किसी कार्य के लिए सही मोड चुनने में मदद करता है।",
+		"resetToDefault": "'कब उपयोग करें' विवरण को डिफ़ॉल्ट पर रीसेट करें"
+	},
 	"customInstructions": {
 		"title": "मोड-विशिष्ट कस्टम निर्देश (वैकल्पिक)",
 		"resetToDefault": "डिफ़ॉल्ट पर रीसेट करें",
@@ -131,6 +136,10 @@
 			"label": "भूमिका परिभाषा",
 			"description": "इस मोड के लिए Roo की विशेषज्ञता और व्यक्तित्व परिभाषित करें।"
 		},
+		"whenToUse": {
+			"label": "कब उपयोग करें (वैकल्पिक)",
+			"description": "स्पष्ट रूप से बताएं कि यह मोड कब सबसे प्रभावी है और किस प्रकार के कार्यों में यह उत्कृष्ट है।"
+		},
 		"tools": {
 			"label": "उपलब्ध टूल्स",
 			"description": "चुनें कि यह मोड कौन से टूल्स उपयोग कर सकता है।"

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Ripristina predefiniti",
 		"description": "Definisci l'esperienza e la personalità di Roo per questa modalità. Questa descrizione modella come Roo si presenta e affronta i compiti."
 	},
+	"whenToUse": {
+		"title": "Quando utilizzare (opzionale)",
+		"description": "Descrivi quando questa modalità dovrebbe essere utilizzata. Questo aiuta l'Orchestrator a scegliere la modalità giusta per un compito.",
+		"resetToDefault": "Ripristina la descrizione 'Quando utilizzare' ai valori predefiniti"
+	},
 	"customInstructions": {
 		"title": "Istruzioni personalizzate specifiche per la modalità (opzionale)",
 		"resetToDefault": "Ripristina predefiniti",
@@ -131,6 +136,10 @@
 			"label": "Definizione del ruolo",
 			"description": "Definisci l'esperienza e la personalità di Roo per questa modalità."
 		},
+		"whenToUse": {
+			"label": "Quando utilizzare (opzionale)",
+			"description": "Fornisci una chiara descrizione di quando questa modalità è più efficace e per quali tipi di compiti eccelle."
+		},
 		"tools": {
 			"label": "Strumenti disponibili",
 			"description": "Seleziona quali strumenti questa modalità può utilizzare."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "デフォルトにリセット",
 		"description": "このモードのRooの専門知識と個性を定義します。この説明は、Rooが自身をどのように表現し、タスクにどのように取り組むかを形作ります。"
 	},
+	"whenToUse": {
+		"title": "使用タイミング（オプション）",
+		"description": "このモードをいつ使用すべきかを説明します。これはOrchestratorがタスクに適切なモードを選択するのに役立ちます。",
+		"resetToDefault": "「使用タイミング」説明をデフォルトにリセット"
+	},
 	"customInstructions": {
 		"title": "モード固有のカスタム指示（オプション）",
 		"resetToDefault": "デフォルトにリセット",
@@ -131,6 +136,10 @@
 			"label": "役割の定義",
 			"description": "このモードのRooの専門知識と個性を定義します。"
 		},
+		"whenToUse": {
+			"label": "使用タイミング（オプション）",
+			"description": "このモードが最も効果的なタイミングと、どのようなタイプのタスクに適しているかを明確に説明します。"
+		},
 		"tools": {
 			"label": "利用可能なツール",
 			"description": "このモードが使用できるツールを選択します。"

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "기본값으로 재설정",
 		"description": "이 모드에 대한 Roo의 전문성과 성격을 정의하세요. 이 설명은 Roo가 자신을 어떻게 표현하고 작업에 접근하는지 형성합니다."
 	},
+	"whenToUse": {
+		"title": "사용 시기 (선택 사항)",
+		"description": "이 모드를 언제 사용해야 하는지 설명합니다. 이는 Orchestrator가 작업에 적합한 모드를 선택하는 데 도움이 됩니다.",
+		"resetToDefault": "'사용 시기' 설명을 기본값으로 재설정"
+	},
 	"customInstructions": {
 		"title": "모드별 사용자 지정 지침 (선택 사항)",
 		"resetToDefault": "기본값으로 재설정",
@@ -131,6 +136,10 @@
 			"label": "역할 정의",
 			"description": "이 모드에 대한 Roo의 전문성과 성격을 정의하세요."
 		},
+		"whenToUse": {
+			"label": "사용 시기 (선택 사항)",
+			"description": "이 모드가 가장 효과적인 시기와 어떤 유형의 작업에 적합한지에 대한 명확한 설명을 제공하세요."
+		},
 		"tools": {
 			"label": "사용 가능한 도구",
 			"description": "이 모드가 사용할 수 있는 도구를 선택하세요."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Terugzetten naar standaard",
 		"description": "Definieer Roo's expertise en persoonlijkheid voor deze modus. Deze beschrijving bepaalt hoe Roo zich presenteert en taken benadert."
 	},
+	"whenToUse": {
+		"title": "Wanneer te gebruiken (optioneel)",
+		"description": "Beschrijf wanneer deze modus gebruikt moet worden. Dit helpt de Orchestrator om de juiste modus voor een taak te kiezen.",
+		"resetToDefault": "Beschrijving 'Wanneer te gebruiken' terugzetten naar standaard"
+	},
 	"customInstructions": {
 		"title": "Modusspecifieke instructies (optioneel)",
 		"resetToDefault": "Terugzetten naar standaard",
@@ -131,6 +136,10 @@
 			"label": "Roldefinitie",
 			"description": "Definieer Roo's expertise en persoonlijkheid voor deze modus."
 		},
+		"whenToUse": {
+			"label": "Wanneer te gebruiken (optioneel)",
+			"description": "Geef een duidelijke beschrijving van wanneer deze modus het meest effectief is en voor welke soorten taken deze uitblinkt."
+		},
 		"tools": {
 			"label": "Beschikbare tools",
 			"description": "Selecteer welke tools deze modus kan gebruiken."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Przywróć domyślne",
 		"description": "Zdefiniuj wiedzę specjalistyczną i osobowość Roo dla tego trybu. Ten opis kształtuje, jak Roo prezentuje się i podchodzi do zadań."
 	},
+	"whenToUse": {
+		"title": "Kiedy używać (opcjonalne)",
+		"description": "Opisz, kiedy ten tryb powinien być używany. Pomaga to Orchestratorowi wybrać odpowiedni tryb dla zadania.",
+		"resetToDefault": "Przywróć domyślny opis 'Kiedy używać'"
+	},
 	"customInstructions": {
 		"title": "Niestandardowe instrukcje dla trybu (opcjonalne)",
 		"resetToDefault": "Przywróć domyślne",
@@ -131,6 +136,10 @@
 			"label": "Definicja roli",
 			"description": "Zdefiniuj wiedzę specjalistyczną i osobowość Roo dla tego trybu."
 		},
+		"whenToUse": {
+			"label": "Kiedy używać (opcjonalne)",
+			"description": "Podaj jasny opis, kiedy ten tryb jest najbardziej efektywny i w jakich typach zadań się sprawdza."
+		},
 		"tools": {
 			"label": "Dostępne narzędzia",
 			"description": "Wybierz, których narzędzi może używać ten tryb."

webview-ui/src/i18n/locales/pt-BR/prompts.json

@@ -34,6 +34,11 @@
 		"resetToDefault": "Restaurar para padrão",
 		"description": "Defina a expertise e personalidade do Roo para este modo. Esta descrição molda como o Roo se apresenta e aborda tarefas."
 	},
+	"whenToUse": {
+		"title": "Quando usar (opcional)",
+		"description": "Descreva quando este modo deve ser usado. Isso ajuda o Orchestrator a escolher o modo certo para uma tarefa.",
+		"resetToDefault": "Restaurar descrição 'Quando usar' para padrão"
+	},
 	"customInstructions": {
 		"title": "Instruções personalizadas específicas do modo (opcional)",
 		"resetToDefault": "Restaurar para padrão",
@@ -131,6 +136,10 @@
 			"label": "Definição de função",
 			"description": "Defina a expertise e personalidade do Roo para este modo."
 		},
+		"whenToUse": {
+			"label": "Quando usar (opcional)",
+			"description": "Forneça uma descrição clara de quando este modo é mais eficaz e para quais tipos de tarefas ele se destaca."
+		},
 		"tools": {
 			"label": "Ferramentas disponíveis",
 			"description": "Selecione quais ferramentas este modo pode usar."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Сбросить по умолчанию",
 		"description": "Определите экспертность и личность Roo для этого режима. Это описание формирует, как Roo будет себя вести и выполнять задачи."
 	},
+	"whenToUse": {
+		"title": "Когда использовать (необязательно)",
+		"description": "Опишите, когда следует использовать этот режим. Это помогает Orchestrator выбрать правильный режим для задачи.",
+		"resetToDefault": "Сбросить описание 'Когда использовать' по умолчанию"
+	},
 	"customInstructions": {
 		"title": "Пользовательские инструкции для режима (необязательно)",
 		"resetToDefault": "Сбросить по умолчанию",
@@ -131,6 +136,10 @@
 			"label": "Определение роли",
 			"description": "Определите экспертность и личность Roo для этого режима."
 		},
+		"whenToUse": {
+			"label": "Когда использовать (необязательно)",
+			"description": "Предоставьте четкое описание, когда этот режим наиболее эффективен и для каких типов задач он лучше всего подходит."
+		},
 		"tools": {
 			"label": "Доступные инструменты",
 			"description": "Выберите, какие инструменты может использовать этот режим."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Varsayılana sıfırla",
 		"description": "Bu mod için Roo'nun uzmanlığını ve kişiliğini tanımlayın. Bu açıklama, Roo'nun kendini nasıl sunduğunu ve görevlere nasıl yaklaştığını şekillendirir."
 	},
+	"whenToUse": {
+		"title": "Ne zaman kullanılmalı (isteğe bağlı)",
+		"description": "Bu modun ne zaman kullanılması gerektiğini açıklayın. Bu, Orchestrator'ın bir görev için doğru modu seçmesine yardımcı olur.",
+		"resetToDefault": "'Ne zaman kullanılmalı' açıklamasını varsayılana sıfırla"
+	},
 	"customInstructions": {
 		"title": "Moda özgü özel talimatlar (isteğe bağlı)",
 		"resetToDefault": "Varsayılana sıfırla",
@@ -131,6 +136,10 @@
 			"label": "Rol Tanımı",
 			"description": "Bu mod için Roo'nun uzmanlığını ve kişiliğini tanımlayın."
 		},
+		"whenToUse": {
+			"label": "Ne zaman kullanılmalı (isteğe bağlı)",
+			"description": "Bu modun ne zaman en etkili olduğu ve hangi tür görevlerde üstün olduğu hakkında net bir açıklama sağlayın."
+		},
 		"tools": {
 			"label": "Kullanılabilir Araçlar",
 			"description": "Bu modun hangi araçları kullanabileceğini seçin."

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

@@ -34,6 +34,11 @@
 		"resetToDefault": "Đặt lại về mặc định",
 		"description": "Xác định chuyên môn và tính cách của Roo cho chế độ này. Mô tả này định hình cách Roo giới thiệu bản thân và tiếp cận nhiệm vụ."
 	},
+	"whenToUse": {
+		"title": "Khi nào nên sử dụng (tùy chọn)",
+		"description": "Mô tả khi nào nên sử dụng chế độ này. Điều này giúp Orchestrator chọn chế độ phù hợp cho một nhiệm vụ.",
+		"resetToDefault": "Đặt lại mô tả 'Khi nào nên sử dụng' về mặc định"
+	},
 	"customInstructions": {
 		"title": "Hướng dẫn tùy chỉnh dành riêng cho chế độ (tùy chọn)",
 		"resetToDefault": "Đặt lại về mặc định",
@@ -131,6 +136,10 @@
 			"label": "Định nghĩa vai trò",
 			"description": "Xác định chuyên môn và tính cách của Roo cho chế độ này."
 		},
+		"whenToUse": {
+			"label": "Khi nào nên sử dụng (tùy chọn)",
+			"description": "Cung cấp mô tả rõ ràng về thời điểm chế độ này hiệu quả nhất và những loại nhiệm vụ nào nó thực hiện tốt nhất."
+		},
 		"tools": {
 			"label": "Công cụ có sẵn",
 			"description": "Chọn công cụ nào chế độ này có thể sử dụng."

webview-ui/src/i18n/locales/zh-CN/prompts.json

@@ -34,6 +34,11 @@
 		"resetToDefault": "重置为默认值",
 		"description": "设定专业领域和应答风格"
 	},
+	"whenToUse": {
+		"title": "使用场景（可选）",
+		"description": "描述何时应该使用此模式。这有助于 Orchestrator 为任务选择合适的模式。",
+		"resetToDefault": "重置\"使用场景\"描述为默认值"
+	},
 	"customInstructions": {
 		"title": "模式专属规则（可选）",
 		"resetToDefault": "重置为默认值",
@@ -131,6 +136,10 @@
 			"label": "角色定义",
 			"description": "设定专业方向"
 		},
+		"whenToUse": {
+			"label": "使用场景（可选）",
+			"description": "清晰描述此模式最适合的场景和任务类型"
+		},
 		"tools": {
 			"label": "可用工具",
 			"description": "选择可用工具"

webview-ui/src/i18n/locales/zh-TW/prompts.json

@@ -34,6 +34,11 @@
 		"resetToDefault": "重設為預設值",
 		"description": "定義此模式下 Roo 的專業知識和個性。此描述會形塑 Roo 如何展現自己並處理工作。"
 	},
+	"whenToUse": {
+		"title": "使用時機（選用）",
+		"description": "描述何時應使用此模式。這有助於 Orchestrator 為任務選擇適當的模式。",
+		"resetToDefault": "重設「使用時機」描述為預設值"
+	},
 	"customInstructions": {
 		"title": "模式專屬自訂指令（選用）",
 		"resetToDefault": "重設為預設值",
@@ -131,6 +136,10 @@
 			"label": "角色定義",
 			"description": "定義此模式下 Roo 的專業知識和個性。"
 		},
+		"whenToUse": {
+			"label": "使用時機（選用）",
+			"description": "提供清晰的描述，說明此模式最適合什麼時候使用，以及適合哪些類型的任務。"
+		},
 		"tools": {
 			"label": "可用工具",
 			"description": "選擇此模式可使用的工具。"

webview-ui/src/utils/context-mentions.ts

@@ -135,13 +135,13 @@ export function getContextMenuOptions(
 					type: ContextMenuOptionType.Mode,
 					value: result.item.original.slug,
 					label: result.item.original.name,
-					description: result.item.original.roleDefinition.split("\n")[0],
+					description: (result.item.original.whenToUse || result.item.original.roleDefinition).split("\n")[0],
 				}))
 			: modes.map((mode) => ({
 					type: ContextMenuOptionType.Mode,
 					value: mode.slug,
 					label: mode.name,
-					description: mode.roleDefinition.split("\n")[0],
+					description: (mode.whenToUse || mode.roleDefinition).split("\n")[0],
 				}))
 
 		return matchingModes.length > 0 ? matchingModes : [{ type: ContextMenuOptionType.NoResults }]