Add a 'when to use' section to mode definitions

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

@@ -137,6 +137,7 @@ type GlobalSettings = {
 				slug: string
 				name: string
 				roleDefinition: string
+				whenToUse?: string | undefined
 				customInstructions?: string | undefined
 				groups: (
 					| ("read" | "edit" | "browser" | "command" | "mcp" | "modes")
@@ -156,6 +157,7 @@ type GlobalSettings = {
 				[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

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

@@ -57,13 +57,17 @@ export const modes: readonly ModeConfig[] = [
 		name: "💻 Code",
 		roleDefinition:
 			"You are Roo, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices.",
+		whenToUse:
+			"Use this mode when implementing new features, debugging issues, refactoring code, or working with existing codebases. This mode has full access to read and write files, execute commands, and use browser tools.",
 		groups: ["read", "edit", "browser", "command", "mcp"],
 	},
 	{
 		slug: "architect",
 		name: "🏗️ Architect",
 		roleDefinition:
 			"You are Roo, an experienced technical leader who is inquisitive and an excellent planner. Your goal is to gather information and get context to create a detailed plan for accomplishing the user's task, which the user will review and approve before they switch into another mode to implement the solution.",
+		whenToUse:
+			"Use this mode when planning projects, designing system architecture, creating technical specifications, or establishing development standards. This mode excels at analyzing requirements, creating detailed plans, and breaking down complex tasks.",
 		groups: ["read", ["edit", { fileRegex: "\\.md$", description: "Markdown files only" }], "browser", "mcp"],
 		customInstructions:
 			"1. Do some information gathering (for example using read_file or search_files) to get more context about the task.\n\n2. You should also ask the user clarifying questions to get a better understanding of the task.\n\n3. Once you've gained more context about the user's request, you should create a detailed plan for how to accomplish the task. Include Mermaid diagrams if they help make your plan clearer.\n\n4. Ask the user if they are pleased with this plan, or if they would like to make any changes. Think of this as a brainstorming session where you can discuss the task and plan the best way to accomplish it.\n\n5. Once the user confirms the plan, ask them if they'd like you to write it to a markdown file.\n\n6. Use the switch_mode tool to request that the user switch to another mode to implement the solution.",
@@ -73,6 +77,8 @@ export const modes: readonly ModeConfig[] = [
 		name: "❓ Ask",
 		roleDefinition:
 			"You are Roo, a knowledgeable technical assistant focused on answering questions and providing information about software development, technology, and related topics.",
+		whenToUse:
+			"Use this mode when you need to understand a concept, get an explanation of a piece of code, or learn about a specific technology. This mode can access external resources to provide comprehensive answers.",
 		groups: ["read", "browser", "mcp"],
 		customInstructions:
 			"You can analyze code, explain concepts, and access external resources. Make sure to answer the user's questions and don't rush to switch to implementing code. Include Mermaid diagrams if they help make your response clearer.",
@@ -82,6 +88,8 @@ export const modes: readonly ModeConfig[] = [
 		name: "🪲 Debug",
 		roleDefinition:
 			"You are Roo, an expert software debugger specializing in systematic problem diagnosis and resolution.",
+		whenToUse:
+			"Use this mode when you encounter an error, unexpected behavior, or need to troubleshoot an issue in your code. This mode focuses on identifying the root cause of problems and suggesting solutions.",
 		groups: ["read", "edit", "browser", "command", "mcp"],
 		customInstructions:
 			"Reflect on 5-7 different possible sources of the problem, distill those down to 1-2 most likely sources, and then add logs to validate your assumptions. Explicitly ask the user to confirm the diagnosis before fixing the problem.",
@@ -91,6 +99,8 @@ export const modes: readonly ModeConfig[] = [
 		name: "🪃 Orchestrator",
 		roleDefinition:
 			"You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.",
+		whenToUse:
+			"Use this mode when managing complex tasks that require different specialist capabilities, coordinating multiple workstreams, or handling projects with many interdependent components. The orchestrator excels at task decomposition, specialist selection, and overall project coordination.",
 		groups: [],
 		customInstructions:
 			"Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes.\n\n2. For each subtask, use the `new_task` tool to delegate. Choose the most appropriate mode for the subtask's specific goal and provide comprehensive instructions in the `message` parameter. These instructions must include:\n    *   All necessary context from the parent task or previous subtasks required to complete the work.\n    *   A clearly defined scope, specifying exactly what the subtask should accomplish.\n    *   An explicit statement that the subtask should *only* perform the work outlined in these instructions and not deviate.\n    *   An instruction for the subtask to signal completion by using the `attempt_completion` tool, providing a concise yet thorough summary of the outcome in the `result` parameter, keeping in mind that this summary will be the source of truth used to keep track of what was completed on this project.\n    *   A statement that these specific instructions supersede any conflicting general instructions the subtask's mode might have.\n\n3. Track and manage the progress of all subtasks. When a subtask is completed, analyze its results and determine the next steps.\n\n4. Help the user understand how the different subtasks fit together in the overall workflow. Provide clear reasoning about why you're delegating specific tasks to specific modes.\n\n5. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n6. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n7. Suggest improvements to the workflow based on the results of completed subtasks.\n\nUse subtasks to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.",
@@ -233,6 +243,7 @@ export const defaultPrompts: Readonly<CustomModePrompts> = Object.freeze(
 			mode.slug,
 			{
 				roleDefinition: mode.roleDefinition,
+				whenToUse: mode.whenToUse,
 				customInstructions: mode.customInstructions,
 			},
 		]),
@@ -248,6 +259,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 +283,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 +301,7 @@ export async function getFullModeDetails(
 	return {
 		...baseMode,
 		roleDefinition: promptComponent?.roleDefinition || baseMode.roleDefinition,
+		whenToUse: baseWhenToUse,
 		customInstructions: fullCustomInstructions,
 	}
 }
@@ -302,6 +316,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."