Week 3: Plan vs. Build — Using Built-in Agents¶

Why This Week Matters¶

By the end of Week 2, you know how to run OpenCode and ask it to fix things. This week teaches you the most important judgment skill: when to explore before executing.

Many beginners jump straight into making changes. That feels fast, but it often creates more work: the agent misses context, edits the wrong files, or leaves your code in a half-broken state. Experienced engineers explore first, write down what they learned, and then execute.

This week, you'll learn to use two built-in agents — plan (read-only, safe) and build (full-access, changes things) — and flip between them with a single keystroke. By the end, you'll know:

What the plan agent is and why it prevents mistakes.
How to switch between plan and build modes.
The "explore → write a plan → execute" workflow that pros use.
When to stay in plan mode even after you've understood the problem.

The Problem: Jumping Straight to Build¶

Let's say you're debugging a crash in a Node.js app. Here's what happens if you go straight to the build agent:

You: "Fix the null pointer bug."

Build agent (no context, full access): - Looks at 1–2 files. - Sees const x = data.foo; and thinks "maybe add a check." - Edits three unrelated functions while it's at it. - Adds a console.log that wasn't needed. - Commits without running tests.

Result: You spend 10 minutes undoing the mess.

Now, what if you explored first?

You (in plan mode): "Find the null pointer bug."

Plan agent (read-only, safe to explore): - Reads the error stack trace. - Checks the caller of the broken function. - Finds the root cause: a conditional that didn't guard against undefined. - Writes a 3-bullet plan: (1) Add a null check. (2) Trace where the bad value comes from. (3) Test with the original failing case.

You: "Good. Switch to build."

Build agent (now focused): - Applies only the 3-step plan. - Runs tests. - Commits with a clear message.

Result: 2 minutes total. The bug is fixed and the repo is clean.

The difference: judgment. The plan agent forced you to think before acting.

The Two Built-in Agents¶

OpenCode ships with three agents built in. You met two in Week 2 (plan and build). There's also a third — general — which is a utility agent for searches. We'll cover subagents properly in Week 6. This week, we focus on two of them:

`plan` — Read-Only Explorer¶

What it can do: Read files, browse the codebase, run searches, see output, suggest changes.
What it cannot do: Edit files, run bash commands, or make commits.
Why use it: To understand a problem safely. No risk of breaking things.
Feels like: A detective interviewing the codebase before disturbing anything.

`build` — Full-Access Executor¶

What it can do: Everything — read, edit, run bash, commit, delete.
What it cannot do: Nothing (except what you've explicitly denied in permissions).
Why use it: To actually ship work.
Feels like: A carpenter with a full toolbox, trusted to use it.

Bonus: `general` — A Subagent for Searches¶

You won't use this interactively, but when plan or build need to search a large codebase or look something up, they can delegate to general (a fast, read-only subagent). We'll cover subagents properly in Week 6.

Switching Modes: The Tab Key¶

The simplest part: press Tab to toggle between plan and build.

[OpenCode TUI]
Your message: Find the bug in auth.js
(Build mode, ready to edit)

[You press Tab]
[TUI updates]
(Plan mode, read-only)

[You press Tab again]
[TUI updates]
(Build mode, ready to edit)

No reloading. No restart. Just Tab.

Pro tip: Many learners don't know this shortcut exists. Look at the TUI at the top — you'll see [Plan] or [Build] displayed. Press Tab to swap.

The Approval Prompts: When Does It Ask Permission?¶

In Week 2, you may have seen the agent ask "Can I edit this file?" before making a change. That's the permission system at work.

Here's when approval happens:

Action	Plan Mode	Build Mode
Read a file	✓ automatic	✓ automatic
Grep/search	✓ automatic	✓ automatic
Edit a file	✗ blocked	↔️ asks*
Run bash	✗ blocked	↔️ asks*
Delete files	✗ blocked	↔️ asks*

*In build mode, approval depends on your project's opencode.jsonc. See the cheatsheet for examples.

What to look for in a prompt: - Does it show the file it wants to edit? - Does it show the old/new code? - Can you understand why it's making the change?

If the answer is "no" to any of these, deny it and ask the agent to explain first (in plan mode).

The Tools Behind the Agents¶

Agents don't think — they act. Every action an agent takes — reading a file, searching for a pattern, running a command, fetching a URL — uses one of OpenCode's built-in tools. Knowing the toolset helps you understand what the agent can and cannot do.

The Full Tool List¶

Tool	What It Does	Controlled By
`bash`	Run shell commands	`bash` permission
`read`	View file contents	`read` permission
`write`	Create new files	`edit` permission
`edit`	Modify existing files	`edit` permission
`patch`	Apply a diff to a file	`edit` permission
`glob`	Find files by name pattern	`glob` permission
`grep`	Search file contents	`grep` permission
`ls`	List directory contents	`read` permission
`fetch`	Get content from URLs	`webfetch` permission
`sourcegraph`	Search code in public repos	`websearch` permission
`diagnostics`	Check for linter/compiler errors	`lsp` permission
`agent`	Invoke a subagent	`task` permission

Tools You Haven't Seen Yet¶

fetch: The agent can read web content — documentation pages, API responses, public data. The plan agent uses this to look up libraries or verify facts. It's controlled by the webfetch permission.

sourcegraph: Search code across millions of public GitHub repositories. If the agent needs to find how a library is used in real projects, it can use Sourcegraph to look it up.

diagnostics: Get real-time errors and warnings from your editor's language server. The agent can check a file for problems without running the compiler yourself.

patch: Instead of rewriting an entire file, the agent can apply a focused diff (like a git patch). This is safer for large files because it only changes the lines specified.

Why learn this now? In Week 6, you'll set permissions per agent — allowing some tools and denying others. Knowing the full toolset lets you design agents that have exactly the access they need, nothing more.

The Workflow: Explore → Plan → Execute¶

Here's the three-step pattern used by experienced engineers:

Step 1: Explore (Plan Mode)¶

Start every non-trivial task in plan mode.

$ opencode
>> "Investigate why the tests are failing"

[Agent reads test output, traces the bug]
[No edits, no risk]

What you're looking for: - Does the agent understand the problem? - Are there files it missed? - Did it find the root cause or just a symptom?

If the answer is "no" to any of these, ask follow-up questions in plan mode. Stay in plan mode as long as you're still learning.

Step 2: Write a Plan (Still Plan Mode)¶

Before switching to build, ask the agent to summarize:

>> "Based on what you found, write a 5-bullet plan to fix this"

[Agent writes a concrete plan]
[You review it]

What a good plan looks like: - Specific file names, not "edit the auth module." - One action per bullet. - In order (do step 1 before step 2). - No more than 5–7 steps for a beginner task.

If the plan is fuzzy or unclear, stay in plan mode and ask the agent to refine it. Do not move forward with a half-baked plan.

Step 3: Execute (Build Mode)¶

Once you approve the plan, flip to build mode and execute:

[Press Tab to switch to Build mode]

>> "Apply the plan we just wrote"

[Agent edits files, runs tests, commits]

What can go wrong here: - The agent deviates from the plan (do not approve the edits). - The agent over-engineers (adds stuff that wasn't in the plan). - The agent fails to test (ask it to run tests before committing).

If any of this happens, deny the approval and flip back to plan mode to debug. There's no penalty for saying "no."

Case Study: One Task, Two Ways¶

Let's walk through a real example to see the difference.

Scenario¶

You have a Node.js HTTP server that crashes sometimes. The error is:

TypeError: Cannot read property 'id' of undefined
  at line 45 of routes/user.js

You have 2 minutes to fix it.

Approach A: Jump Straight to Build (❌ Don't Do This)¶

$ opencode
>> "Fix the crash in routes/user.js line 45"

[Build agent, 10 seconds thinking]
[Edits routes/user.js, middleware.js, and config.js]
[Adds 3 console.logs]
[Commits: "Fix crash"]

[You run tests]
Tests fail. The crash is fixed, but the agent broke something else.

Time wasted: 5–10 minutes debugging the agent's unintended changes.

Approach B: Explore First (✅ Do This)¶

$ opencode
>> "Why does line 45 of routes/user.js crash?"

[Plan agent, reads the code]
[Finds: the function expects `request.user`, but sometimes it's undefined]
[Digs deeper: traces where `request.user` is set (in middleware)]
[Finds: one route bypasses the middleware]

[Plan agent writes its findings in 3 bullets]

Then:

>> "Write a 5-step fix plan"

[Plan agent proposes]
1. Add a guard: check if request.user exists
2. If not, return a 401 response
3. Add a unit test for the bypass case
4. Run the full test suite
5. Commit with a message explaining why

You review the plan. It's good. Then:

[Press Tab to switch to Build mode]

>> "Apply the plan"

[Build agent, focused and constrained, applies each step]
[Tests pass]
[Commits: "Fix: add user auth check in routes/user.js"]

Done in 2 minutes total.

Why this works: The plan agent did the detective work, you reviewed it, and the build agent just followed orders.

When to Stay in Plan Mode (Judgment Call)¶

Even after you understand a problem, sometimes you should not switch to build mode. These are cases where human judgment is better than automation:

1. Security Audits¶

"Review this config file for secrets."

You want a careful, non-intrusive review.
If the agent finds a secret, you might want to handle the cleanup yourself.
Judgment: Stay in plan mode. Get the report. Then decide what to do.

2. Code Reviews (for Others' Work)¶

"Review this PR for style violations."

You don't want the agent to fix everything automatically.
You want it to point out issues so the PR author learns.
Judgment: Stay in plan mode. Report findings. Let the author fix it.

3. Unfamiliar Codebases¶

"Understand how this 50-file package works."

You need to learn the architecture before touching anything.
If the agent auto-edits, you might miss important patterns.
Judgment: Stay in plan mode. Ask it to explain. Draw a diagram. Only edit once you understand.

4. Multi-File Refactors¶

"Rename API_HOST to API_BASE_URL everywhere."

A misplaced edit could break something subtle.
You want to see every change before it's committed.
Judgment: Stay in plan mode. Get a list of files to change. Vet the plan. Then switch to build with a specific, approved list.

5. Performance-Critical Code¶

"Optimize the database query in models/user.js."

A change that "works" might be slower.
You need to benchmark before and after.
Judgment: Stay in plan mode. Let the agent suggest optimizations. Then you test and approve.

Rule of thumb: If you wouldn't let a junior engineer auto-commit without a code review, don't let the build agent either. Use plan mode as your review step.

Approval Prompts: Reading Them Right¶

When the build agent asks "Can I edit this?", you get a message like:

Permission: Edit file /path/to/src/app.js?
Old:
```javascript
const config = require('./config');
if (config.debug) console.log('Starting...');

New:

const config = require('./config');
if (config.debug) {
  console.log('Starting at', new Date());
}

Approve? [y/n/ask-for-clarification] ```

Your checklist before approving:

✓ Do I recognize this file?
✓ Does the change make sense in context?
✓ Is it the only change the agent proposed (not sneaking in extras)?
✓ If I denied this, could I explain why to my team?

If you check all four, approve it. If not, type ask or n and ask the agent to explain.

Summary: The Key Judgment Shift¶

Week 1–2 thinking: "Just do it. Make the changes."

Week 3 thinking: "Wait. Let me explore first. Write it down. Then do it."

This shift — from impulsive to deliberate — is the single biggest productivity gain in the course. The time you spend in plan mode is not wasted; it's saved time that you don't spend debugging.

Ready for the Lab?¶

Next: Lab 3.1 — Investigate a Bug in Plan Mode.

You'll use the plan agent to explore a small but tricky bug in a sample Node.js app, write a 5-bullet fix plan without making any changes, then switch to build and execute.

No breaks. You've got this.