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

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

* Remove defaults for now

Author: mrubens

.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."