feat(custom-instructions): migrate custom instructions to file-based storage

See discussion: #4000

Migrated the storage of "Custom Instructions for All Modes" from VS Code's global state to a dedicated file: `...Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/custom_instructions.md`.

Key changes include:
- Implemented a migration utility to automatically move existing custom instructions from global state to the new file upon extension update.
- Introduced new commands and UI buttons within the Prompts view to:
  - Open the `custom_instructions.md` file directly in the editor for easy editing.
  - Refresh the custom instructions in the UI by re-reading them from the file, ensuring changes made directly to the file are reflected.
- The `updateCustomInstructions` function now writes/deletes the file instead of updating global state.
- The initial state and refreshes now read custom instructions directly from the file.

This change provides a more robust and user-friendly way to manage custom instructions, allowing for external editing and version control.

Author: devxpain

src/core/webview/ClineProvider.ts

@@ -989,11 +989,47 @@ export class ClineProvider
 	}
 
 	async updateCustomInstructions(instructions?: string) {
-		// User may be clearing the field.
-		await this.updateGlobalState("customInstructions", instructions || undefined)
+		const settingsDirPath = await this.ensureSettingsDirectoryExists()
+		const customInstructionsFilePath = path.join(settingsDirPath, GlobalFileNames.customInstructions)
+
+		if (instructions && instructions.trim()) {
+			await fs.writeFile(customInstructionsFilePath, instructions.trim(), "utf-8")
+		} else {
+			// If instructions are empty or undefined, delete the file if it exists
+			try {
+				await fs.unlink(customInstructionsFilePath)
+			} catch (error) {
+				// Ignore if file doesn't exist
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+					throw error
+				}
+			}
+		}
 		await this.postStateToWebview()
 	}
 
+	async openCustomInstructionsFile(): Promise<void> {
+		const settingsDirPath = await this.ensureSettingsDirectoryExists()
+		const customInstructionsFilePath = path.join(settingsDirPath, GlobalFileNames.customInstructions)
+		const fileUri = vscode.Uri.file(customInstructionsFilePath)
+		await vscode.commands.executeCommand("vscode.open", fileUri, { preview: false, preserveFocus: true })
+		await vscode.commands.executeCommand("workbench.action.files.revert", fileUri)
+	}
+
+	async refreshCustomInstructions(): Promise<void> {
+		const settingsDirPath = await this.ensureSettingsDirectoryExists()
+		const customInstructionsFilePath = path.join(settingsDirPath, GlobalFileNames.customInstructions)
+		let content: string | undefined = undefined
+		try {
+			content = await fs.readFile(customInstructionsFilePath, "utf-8")
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+				throw error
+			}
+		}
+		await this.updateCustomInstructions(content)
+	}
+
 	// MCP
 
 	async ensureMcpServersDirectoryExists(): Promise<string> {
@@ -1025,6 +1061,21 @@ export class ClineProvider
 		return getSettingsDirectoryPath(globalStoragePath)
 	}
 
+	private async readCustomInstructionsFromFile(): Promise<string | undefined> {
+		const settingsDirPath = await this.ensureSettingsDirectoryExists()
+		const customInstructionsFilePath = path.join(settingsDirPath, GlobalFileNames.customInstructions)
+
+		if (await fileExistsAtPath(customInstructionsFilePath)) {
+			try {
+				return await fs.readFile(customInstructionsFilePath, "utf-8")
+			} catch (error) {
+				this.log(`Error reading custom instructions file: ${error}`)
+				return undefined
+			}
+		}
+		return undefined
+	}
+
 	// OpenRouter
 
 	async handleOpenRouterCallback(code: string) {
@@ -1474,7 +1525,7 @@ export class ClineProvider
 		return {
 			apiConfiguration: providerSettings,
 			lastShownAnnouncementId: stateValues.lastShownAnnouncementId,
-			customInstructions: stateValues.customInstructions,
+			customInstructions: await this.readCustomInstructionsFromFile(),
 			apiModelId: stateValues.apiModelId,
 			alwaysAllowReadOnly: stateValues.alwaysAllowReadOnly ?? false,
 			alwaysAllowReadOnlyOutsideWorkspace: stateValues.alwaysAllowReadOnlyOutsideWorkspace ?? false,

src/core/webview/webviewMessageHandler.ts

@@ -16,6 +16,7 @@ import { supportPrompt } from "../../shared/support-prompt"
 import { checkoutDiffPayloadSchema, checkoutRestorePayloadSchema, WebviewMessage } from "../../shared/WebviewMessage"
 import { checkExistKey } from "../../shared/checkExistApiConfig"
 import { experimentDefault } from "../../shared/experiments"
+import { GlobalFileNames } from "../../shared/globalFileNames"
 import { Terminal } from "../../integrations/terminal/Terminal"
 import { openFile, openImage } from "../../integrations/misc/open-file"
 import { selectImages } from "../../integrations/misc/process-images"
@@ -132,6 +133,12 @@ export const webviewMessageHandler = async (provider: ClineProvider, message: We
 		case "customInstructions":
 			await provider.updateCustomInstructions(message.text)
 			break
+		case "openCustomInstructionsFile":
+			await provider.openCustomInstructionsFile()
+			break
+		case "refreshCustomInstructions":
+			await provider.refreshCustomInstructions()
+			break
 		case "alwaysAllowReadOnly":
 			await updateGlobalState("alwaysAllowReadOnly", message.bool ?? undefined)
 			await provider.postStateToWebview()

src/shared/WebviewMessage.ts

@@ -118,6 +118,8 @@ export interface WebviewMessage {
 		| "deleteCustomMode"
 		| "setopenAiCustomModelInfo"
 		| "openCustomModesSettings"
+		| "openCustomInstructionsFile"
+		| "refreshCustomInstructions"
 		| "checkpointDiff"
 		| "checkpointRestore"
 		| "deleteMcpServer"

src/shared/globalFileNames.ts

@@ -3,5 +3,6 @@ export const GlobalFileNames = {
 	uiMessages: "ui_messages.json",
 	mcpSettings: "mcp_settings.json",
 	customModes: "custom_modes.yaml",
+	customInstructions: "custom_instructions.md",
 	taskMetadata: "task_metadata.json",
 }

src/utils/migrateSettings.ts

@@ -34,6 +34,21 @@ export async function migrateSettings(
 
 		// Process each file migration
 		try {
+			// Migrate custom instructions from GlobalState to file
+			const customInstructionsKey = "customInstructions"
+			const customInstructionsContent = context.globalState.get<string>(customInstructionsKey)
+			const customInstructionsFilePath = path.join(settingsDir, GlobalFileNames.customInstructions)
+
+			if (customInstructionsContent && !(await fileExistsAtPath(customInstructionsFilePath))) {
+				await fs.writeFile(customInstructionsFilePath, customInstructionsContent, "utf-8")
+				await context.globalState.update(customInstructionsKey, undefined) // Delete from GlobalState
+				outputChannel.appendLine("Migrated custom instructions from GlobalState to file.")
+			} else {
+				outputChannel.appendLine(
+					`Skipping custom instructions migration: ${customInstructionsContent ? "file already exists" : "no data in GlobalState"}`,
+				)
+			}
+
 			for (const migration of fileMigrations) {
 				const oldPath = path.join(settingsDir, migration.oldName)
 				const newPath = path.join(settingsDir, migration.newName)

webview-ui/src/components/modes/ModesView.tsx

@@ -1036,8 +1036,34 @@ const ModesView = ({ onDone }: ModesViewProps) => {
 					</div>
 				</div>
 
-				<div className="pb-5">
-					<h3 className="text-vscode-foreground mb-3">{t("prompts:globalCustomInstructions.title")}</h3>
+				<div className="pb-5 border-b border-vscode-input-border">
+					<div className="flex justify-between items-center mb-3">
+						<h3 className="text-vscode-foreground m-0">{t("prompts:globalCustomInstructions.title")}</h3>
+						<div className="flex gap-2">
+							<Button
+								variant="ghost"
+								size="icon"
+								onClick={() => {
+									vscode.postMessage({
+										type: "openCustomInstructionsFile",
+									})
+								}}
+								title={t("prompts:globalCustomInstructions.openFile")}>
+								<span className="codicon codicon-go-to-file"></span>
+							</Button>
+							<Button
+								variant="ghost"
+								size="icon"
+								onClick={() => {
+									vscode.postMessage({
+										type: "refreshCustomInstructions",
+									})
+								}}
+								title={t("prompts:globalCustomInstructions.refreshFile")}>
+								<span className="codicon codicon-refresh"></span>
+							</Button>
+						</div>
+					</div>
 
 					<div className="text-sm text-vscode-descriptionForeground mb-2">
 						<Trans i18nKey="prompts:globalCustomInstructions.description">

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

@@ -48,6 +48,8 @@
 	"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. <0>Learn more</0>",
+		"openFile": "Open custom instructions file",
+		"refreshFile": "Refresh custom instructions from file",
 		"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": {