docs: document configurable plan reminders

Author: DuncanCasteleyn

packages/core/src/config/agent.ts

@@ -15,8 +15,14 @@ export class Info extends Schema.Class<Info>("ConfigV2.Agent")({
   variant: Schema.String.pipe(Schema.optional),
   request: ConfigProvider.Request.pipe(Schema.optional),
   system: Schema.String.pipe(Schema.optional),
-  plan_reminder: Schema.String.pipe(Schema.optional),
-  build_switch_reminder: Schema.String.pipe(Schema.optional),
+  plan_reminder: Schema.String.pipe(Schema.optional).annotate({
+    description:
+      "Override the reminder injected when the plan agent enters plan mode. Supports ${planInfo} interpolation.",
+  }),
+  build_switch_reminder: Schema.String.pipe(Schema.optional).annotate({
+    description:
+      "Override the reminder injected when switching from plan mode back to the build agent. Supports ${planInfo} interpolation.",
+  }),
   description: Schema.String.pipe(Schema.optional),
   mode: Schema.Literals(["subagent", "primary", "all"]).pipe(Schema.optional),
   hidden: Schema.Boolean.pipe(Schema.optional),

packages/core/src/v1/config/agent.ts

@@ -18,8 +18,14 @@ const AgentSchema = Schema.StructWithRest(
     temperature: Schema.optional(Schema.Finite),
     top_p: Schema.optional(Schema.Finite),
     prompt: Schema.optional(Schema.String),
-    plan_reminder: Schema.optional(Schema.String),
-    build_switch_reminder: Schema.optional(Schema.String),
+    plan_reminder: Schema.optional(Schema.String).annotate({
+      description:
+        "Override the reminder injected when the plan agent enters plan mode. Supports ${planInfo} interpolation.",
+    }),
+    build_switch_reminder: Schema.optional(Schema.String).annotate({
+      description:
+        "Override the reminder injected when switching from plan mode back to the build agent. Supports ${planInfo} interpolation.",
+    }),
     tools: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)).annotate({
       description: "@deprecated Use 'permission' field instead",
     }),

packages/web/src/content/docs/agents.mdx

@@ -346,6 +346,30 @@ Specify a custom system prompt file for this agent with the `prompt` config. The
 
 This path is relative to where the config file is located. So this works for both the global OpenCode config and the project specific config.
 
+### Plan reminders
+
+The built-in `plan` and `build` agents also support reminder-specific overrides that are separate from the main `prompt`.
+
+- `plan_reminder` customizes the reminder injected when the `plan` agent enters plan mode.
+- `build_switch_reminder` customizes the reminder injected when control returns from `plan` to `build`.
+
+Both fields support `${planInfo}`, which expands to the current plan-file guidance.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "plan": {
+      "plan_reminder": "You are in planning mode.\n\n${planInfo}"
+    },
+    "build": {
+      "build_switch_reminder": "Implementation can begin.\n\n${planInfo}"
+    }
+  }
+}
+```
+
+Use these when you want to customize plan-mode guidance without replacing the agent's full system prompt.
+
 ---
 
 ### Model

packages/web/src/content/docs/config.mdx

@@ -519,6 +519,29 @@ You can configure specialized agents for specific tasks through the `agent` opti
 
 You can also define agents using markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`. [Learn more here](/docs/agents).
 
+Agent configs also support reminder overrides for the built-in plan workflow:
+
+- `plan_reminder` overrides the reminder injected when the `plan` agent enters plan mode.
+- `build_switch_reminder` overrides the reminder injected when control switches back to the `build` agent.
+
+Both fields support `${planInfo}`, which expands to the current plan-file guidance.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "plan": {
+      "plan_reminder": "Plan mode is active.\n\n${planInfo}\n\nKeep the plan concise and execution-ready."
+    },
+    "build": {
+      "build_switch_reminder": "Plan approved. Resume implementation.\n\n${planInfo}"
+    }
+  }
+}
+```
+
+These fields only affect the injected reminder text. They do not change the agent's main `prompt`, and they are unrelated to model catalog settings like `OPENCODE_MODELS_PATH`.
+
 ---
 
 ### Default agent