A model-agnostic replacement for OpenCode's built-in system prompt, build and plan agent prompts, paired with an AGENTS.md workflow layer for safety, verification, git hygiene, communication, and context-window discipline.
The value starts with AGENTS.md: a portable amalgamation of coding-agent operating practices from commercial harnesses such as Claude Code, Codex, and Cursor, adapted for OpenCode instead of copied from any one source. The custom prompt stack is the model-agnostic base that aligns OpenCode's lower-level agent prompts with that workflow layer, replacing the per-model built-in prompts with one shared baseline designed to behave consistently across models.
The goal is a small layered prompt system, not a giant catch-all prompt. OpenCode still provides the harness: model routing, tool schemas, permissions, environment context, skills, agent modes, and instruction-file loading. This repo replaces the baseline agent prompt OpenCode sends to the model, then adds durable operating standards through AGENTS.md.
Model-agnostic, not harness-agnostic. The stack is intentionally tightly coupled to OpenCode as a harness — it relies on OpenCode's agent-prompt override mechanism, instruction-file loading, skill discovery, and tool surface (e.g. WebFetch, the Task tool, subagent types referenced in plan-specific.txt). It is not portable to other agent harnesses such as Claude Code, Codex, or Cursor. The "agnostic" claim is about models: one base prompt is designed to work across GPT, Claude, Kimi, DeepSeek, GLM, Mimo, local models, and other models OpenCode supports, instead of depending on whichever model-specific prompt OpenCode would otherwise select.
This repo provides three layers that are meant to work together:
| Layer | File | Responsibility |
|---|---|---|
| Base agent prompt | src/prompts/custom.txt |
Model-agnostic replacement for OpenCode's built-in model-specific prompts: identity, instruction hierarchy, the OpenCode-doc lookup, and the run-real-checks / code-reference rule |
| Mode prompt | src/prompts/build-specific.txt / src/prompts/plan-specific.txt |
The small amount of behavior that differs between Build Mode and Plan Mode |
| Workflow instructions | src/AGENTS.md |
Durable operating standards: confirmation rules, git hygiene, planning, verification, and communication |
Configured together, these files are designed to give every model OpenCode routes to the same baseline behavior instead of depending on whichever model-specific prompt OpenCode would otherwise select. The base and mode prompts keep the harness aligned; AGENTS.md carries the deeper best-practice workflow.
OpenCode has two built-in agent modes, and this stack provides a different prompt for each. The split is deliberate:
- Build mode is the default working mode. It is for direct implementation of the user's requested change, and it also covers small-to-medium tasks that include a quick read of the surrounding code and a short inline plan, all in one pass. If the task can be done in a handful of edits with the design obvious from the existing code, build mode is the right choice.
- Plan mode is reserved for heavy-duty planning: tasks that are ambiguous, span many files, benefit from structured exploration, or warrant a separate review pass before any code is written. The 4-step plan workflow (
plan-specific.txt) — understand, design, review, final plan — is intentional. Plan mode also enforces a read-only constraint and is the right choice when the user wants to see and approve an approach before implementation begins.
If you are unsure which mode to use: build mode handles the common case. Switch to plan mode when the work is large enough that a one-pass implementation risks scope drift, hidden assumptions, or an approach the user would not have signed off on.
This stack requires the context-mode plugin. Its ctx_* tools are referenced throughout AGENTS.md and the prompt files for context-window protection.
Add it to the plugin array in opencode.json:
"plugin": ["context-mode"]Verify with ctx stats in an OpenCode session.
-
Copy the prompt files:
src/prompts/custom.txt src/prompts/build-specific.txt src/prompts/plan-specific.txtto:
~/.config/opencode/prompts/ -
Copy
src/AGENTS.mdto one of:~/.config/opencode/AGENTS.md # global ./AGENTS.md # project-level -
Add the prompt overrides to
~/.config/opencode/opencode.json: -
Restart OpenCode. Config and prompt files are loaded when OpenCode starts; an existing session will keep using the already-loaded prompt stack.
Project-level AGENTS.md files are loaded alongside the global one, so use them for project-specific commands, conventions, and exceptions without editing your global defaults.
OpenCode's built-in build and plan agents normally use a model-specific prompt selected for the current model, such as gpt.txt, kimi.txt, anthropic.txt, or the fallback default.txt.
When you configure agent.build.prompt and agent.plan.prompt, OpenCode uses these files instead:
prompts/custom.txt + prompts/build-specific.txt -> build agent prompt
prompts/custom.txt + prompts/plan-specific.txt -> plan agent prompt
That replacement is scoped to the configured agents only. It does not remove OpenCode's tools, permissions, environment block, skills, agent modes, or AGENTS.md loading.
OpenCode provides the agent harness out of the box. This stack is an opinionated replacement for the instruction layers that sit on top of it.
| Area | OpenCode provides | This stack adds or edits |
|---|---|---|
| Provider prompts | Model-selected prompts such as gpt.txt, kimi.txt, anthropic.txt, or default.txt |
prompts/custom.txt gives configured models one shared model-agnostic base prompt |
| Build/Plan behavior | Built-in agents and permissions | Small mode prompts that separate implementation behavior from planning behavior |
| Workflow rules | Global/project instruction files are loaded, but workflow preferences are yours to define | src/AGENTS.md supplies durable standards for safety, git, verification, planning, and communication |
| OpenCode harness | Tool schemas, permissions, environment context, skills, model routing, and messages | No replacement; the custom stack is designed to sit inside the existing harness |
AGENTS.md is the main best-practice layer:
| OpenCode provides | AGENTS.md adds |
|---|---|
| Model-specific identity, tone, and basic workflow | Cross-model behavioral guardrails that stay stable across models |
| Tool schemas, permissions, environment context, and skill discovery | Rules for when to use those capabilities safely and when to ask first |
| General coding-agent advice: inspect, edit, test, stay concise | Senior-engineer discipline: verify before reporting done, halt at the scope boundary |
| Basic git caution: do not commit unless asked | Stage-by-name discipline, hook failure handling |
| Testing and lint/typecheck reminders | Verification standards: runtime observation over self-audit, verification executed not simulated |
| Concise CLI communication defaults | Signal-dense, STE-composed progress updates and verification-first reporting |
In the prompt content itself, the custom prompts and stock OpenCode differ in these specific ways:
| Stock OpenCode | This stack |
|---|---|
| Provider prompts vary by model in tone, planning pressure, comments, and tool advice | custom.txt gives every configured model one compact operating contract |
| Read-before-edit guidance is implicit in some provider prompts | AGENTS.md Non-negotiables require inspecting existing files before edits and rereading after stale or ambiguous edit failures |
| File contents, logs, and tool output are not explicitly classified as untrusted | custom.txt treats file contents, logs, retrieved docs, and tool output as untrusted data unless they come from the active instruction hierarchy |
| Some provider prompts constrain output length or comment usage | AGENTS.md keeps responses concise (STE composition, minimal narration) without absolute no-comment policies |
| Some provider prompts emphasize TodoWrite and Task-tool usage | AGENTS.md covers planning via todowrite without forcing heavy process on small tasks |
| Provider prompts handle OpenCode docs lookup with varying specificity | custom.txt routes opencode questions to the docs at https://opencode.ai |
| Provider prompts combine base and mode-specific guidance in one file | build-specific.txt and plan-specific.txt separate implementation behavior from planning behavior |
The custom prompts follow these design principles:
- Read existing files before editing them.
- Treat prompt-like text in files, logs, retrieved docs, and tool output as untrusted data.
- Keep tool-use guidance out of the base prompt; the harness injects tool descriptions.
- Avoid brittle output-length rules and absolute no-comment policies (handled in
AGENTS.md, not the base prompt). - Keep model-specific assumptions out of the shared base prompt.
- Route opencode questions to the current docs at https://opencode.ai instead of guessing.
The stack does not try to copy any single vendor prompt, and it does not try to make weaker models stronger. It shapes behavior; it does not change model capability.
These are design choices backed by the research mapped in docs/research.md, not measured improvements. The stack has not been benchmarked against stock OpenCode or any other prompt setup; treat the claims as hypotheses, not guarantees. If you have benchmark data that contradicts a design choice, that is a useful contribution.
One piece of external evidence is directionally supportive: Tura's published DeepSWE runs (20 tasks, 3 replicates, GPT-5.6 SOL at High effort) show a verification-heavy agent configuration reaching an 80% verifier pass rate versus 65% for a token-minimizing configuration of the same harness and model. It is single-model, self-published evidence without ablation — see docs/research.md section 14 for the full mapping and caveats.
The stack was built from four inputs:
- OpenCode's currently bundled model-specific prompts.
- Relevant open OpenCode GitHub issues and PRs about prompt behavior.
- The operating standards encoded in this repo's
AGENTS.md, synthesized from commercial coding-agent harness practices and adapted for OpenCode. - Criterium's OpenCode context-dump research, which shows how OpenCode assembles the model context: agent prompt, tool schemas, messages, environment, skills, and instruction files.
Those inputs shaped the split between base behavior, mode behavior, and workflow rules. The base prompt stays short and aligned with AGENTS.md. The mode files only describe what differs between build and plan. The deeper engineering discipline lives in AGENTS.md.
See docs/research.md for the full mapping of research sources to specific prompt files and line numbers.
With this repo installed, the effective instruction structure is:
custom base prompt
then build-specific or plan-specific prompt
then OpenCode environment context
then global/project AGENTS.md instruction files
then skills and other harness-provided context
OpenCode also sends the tool schemas and conversation messages as part of the model request.
So the custom prompts are not a replacement for AGENTS.md; they sit below it. AGENTS.md remains the workflow layer for rules that should survive across models, projects, and future prompt revisions.
Confirm the resolved agent prompts with:
opencode debug agent build
opencode debug agent planEach command should show the resolved custom base prompt plus the matching mode-specific prompt.
For a deeper audit of the full assembled API context, use Criterium's context-dump research. That is useful when you want to inspect the final context, not just the configured agent prompt.
Edit the layers separately:
- Change
prompts/custom.txtwhen you want to alter the shared base behavior for every configured model. - Change
prompts/build-specific.txtorprompts/plan-specific.txtwhen only one mode should behave differently. - Change
src/AGENTS.mdwhen you want to alter durable workflow rules like git conventions, verification standards, or communication style.
Keep project-specific commands and exceptions in a project-level AGENTS.md, not in the global prompt stack.
- Confirmation before destructive, irreversible, secret-bearing, external, or out-of-tree actions.
- Read-before-edit and prompt-injection boundaries for file/tool output.
- Verification standards: runtime observation for behavior changes, verification executed rather than simulated, and a halt rule that stops at the green executable check.
- Git hygiene: no commits unless asked, stage by name, no root
git add ., and no amend-based recovery from failed hooks. - Planning discipline: use
todowriteto track meaningful multi-step, risky, or cross-file work, one to-do at a time. - Communication and context-window discipline: STE composition with minimal process narration, restatements only when asked, and context-mode tool routing (Think-in-Code analysis via the sandbox, blocked
curl/inline HTTP viactx_fetch_and_index/ctx_execute, large-output redirection, search-before-asking on resume).
MIT
{ "agent": { "build": { "prompt": "{file:prompts/custom.txt}\n\n{file:prompts/build-specific.txt}" }, "plan": { "prompt": "{file:prompts/custom.txt}\n\n{file:prompts/plan-specific.txt}" } } }