docs(core): align built-in prompt guidance (#45642)

.changeset/builtin-prompt-guidance.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/core": patch
+---
+
+Align the built-in review and system prompts with available documentation and code-search tools and the current Plan mode reminder.

packages/core/src/plugin/command/review.txt

@@ -83,7 +83,7 @@ Use best judgement when processing input.
 Use these to inform your review:
 
 - **Explore agent** - Find how existing code handles similar problems. Check patterns, conventions, and prior art before claiming something doesn't fit.
-- **Exa Code Context** - Verify correct usage of libraries/APIs before flagging something as wrong.
+- **Available documentation and code-search tools** - Verify correct usage of libraries/APIs before flagging something as wrong.
 - **Web Search** - Research best practices if you're unsure about a pattern.
 
 If you're uncertain about something and can't verify it with these tools, say "I'm not sure about X" rather than flagging it as a definite issue.

packages/core/src/plugin/system-prompt/meta.txt

@@ -49,7 +49,7 @@ Use the instructions below and the tools available to assist the user.
 
 # Tool Use - OpenCode Specifics
 - When `webfetch` returns a message about a redirect to a different host, you should immediately make a new `webfetch` request with the redirect URL provided in the response.
-- When `plan` mode is active, you will see a <system-reminder> about this. `plan` mode is for planning, not editing. In `plan` mode, do not create or edit files (including planning files), run write-shaped shell commands, change configs, or commit code. If the user is asking you to perform edit operations in `plan` mode, inform them that `plan` mode is active and that they need to switch to build mode.
+- When `plan` mode is active, you will see a <system-reminder> about this. Follow that reminder for the files you may edit and all other Plan mode restrictions. If the user asks you to implement changes, inform them that `plan` mode is active and that they need to switch to build mode.
 
 # Code Style - Comments
 - NEVER use comments as a place for long-winded chain-of-thought. Long thinking texts must be generated as private reasoning. Comments in code must be appropriately concise.

packages/core/test/plugin/command.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect } from "bun:test"
+import { describe, expect, test } from "bun:test"
 import { Effect, Layer } from "effect"
 import { Command } from "@opencode-ai/core/command"
 import { Bus } from "@opencode-ai/core/bus"
@@ -16,6 +16,7 @@ import { emptyMcpLayer } from "../fixture/mcp"
 import { location } from "../fixture/location"
 import { testEffect } from "../lib/effect"
 import { host } from "./host"
+import PROMPT_REVIEW from "../../src/plugin/command/review.txt"
 
 const directory = AbsolutePath.make("/repo/packages/app")
 const project = AbsolutePath.make("/repo")
@@ -31,6 +32,11 @@ const it = testEffect(
 )
 
 describe("CommandPlugin.Plugin", () => {
+  test("refers to tools by their available capabilities", () => {
+    expect(PROMPT_REVIEW).toContain("Available documentation and code-search tools")
+    expect(PROMPT_REVIEW).not.toContain("Exa Code Context")
+  })
+
   it.effect("registers built-in init and review commands", () =>
     Effect.gen(function* () {
       const command = yield* Command.Service

packages/core/test/plugin/system-prompt.test.ts

@@ -44,8 +44,11 @@ describe("SystemPromptPlugin", () => {
     expect(PROMPT_META).toContain("`read` for reading files")
     expect(PROMPT_META).toContain("`edit` for editing")
     expect(PROMPT_META).toContain("`write` for creating files")
+    expect(PROMPT_META).toContain("Follow that reminder for the files you may edit")
     expect(PROMPT_META).toContain("https://opencode.ai/v2/docs/")
-    expect(PROMPT_META).not.toMatch(/TodoWrite|Task tool|WebFetch|\bBash\b|https:\/\/opencode\.ai\/docs/)
+    expect(PROMPT_META).not.toMatch(
+      /TodoWrite|Task tool|WebFetch|\bBash\b|including planning files|https:\/\/opencode\.ai\/docs/,
+    )
   })
 
   test("uses granular IDs with a common prefix", () => {