Week 3: Plan vs. Build¶

Using OpenCode's Built-in Agents¶

The Problem: Jumping Straight to Build¶

You: "Fix the null pointer bug"

Build agent (no context):
✗ Edits three unrelated files
✗ Adds debug logs
✗ Commits without testing

Result: 10 minutes of cleanup

The Solution: Explore First¶

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

Plan agent (read-only):
✓ Reads the error
✓ Traces the root cause
✓ Writes a 3-step plan

You review. Then flip to build.

Build agent (focused):
✓ Applies the plan
✓ Tests pass
✓ Commits

Result: 2 minutes, clean code

Two Built-in Agents¶

Agent	Can Read	Can Edit	Can Bash	Can Commit
plan	✓	✗	✗	✗
build	✓	✓	✓	✓

plan = detective (safe to explore) build = carpenter (full toolbox)

Switching Modes: Press Tab¶

[TUI shows: Plan mode]
       ↓ [You press Tab]
[TUI shows: Build mode]

One keystroke. No restart.

The Approval Prompts¶

When build mode asks permission, check four things:

✓ Do I recognize this file?
✓ Does the change make sense?
✓ Is it the only change?
✓ Can I explain this to my team?

If all yes → approve If any no → deny & ask why

The Three-Step Workflow¶

1. Explore (Plan Mode)¶

Ask the agent to investigate without editing.

2. Write a Plan (Still Plan Mode)¶

Ask for a 5-bullet fix plan. Review it carefully.

3. Execute (Build Mode)¶

Press Tab. Ask the agent to apply the plan.

Stay in plan mode as long as you're learning.

Case Study: The Crash¶

// routes/user.js line 45
const id = request.user.id;  // Crashes when user is undefined

Bad approach: Jump to build → agent edits 3 files → tests fail → cleanup

Good approach: 1. Plan: Why does user become undefined? 2. Plan: Trace to the middleware that sets it 3. Plan: Find which route bypasses the middleware 4. Plan: Write the fix (add a guard, test, commit) 5. Build: Apply the plan

When to Stay in Plan Mode¶

Even after you understand, stay in plan mode for:

Security audits (find secrets, don't auto-fix)
Code reviews (point out issues, let author fix)
Unfamiliar codebases (learn before touching)
Multi-file refactors (review every change first)
Performance tuning (suggest, then you benchmark)

Rule: If you wouldn't let a junior auto-commit, don't let build mode either.

Reading Approval Prompts¶

Permission: Edit src/app.js?

Old:
const debug = config.debug;

New:
const debug = config.debug; // Line 5

Ask yourself: - Do I recognize this file? - Why is this change needed? - Is this the only change? - Is it safe to approve?

The Key Judgment Shift¶

Week 1–2: "Just do it"

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

→ Time in plan mode is saved time. → Fewer mistakes. Cleaner code. → Confidence in what you've asked for.

Your Lab: Investigate a Bug¶

Lab 3.1¶

A Node.js to-do app has a crash.

Use plan mode to investigate (no edits).
Write a 5-bullet plan to fix it.
Flip to build mode.
Execute the plan.
Run tests to confirm.

No jumping straight to build.

Your Second Lab: Stay in Plan¶

Lab 3.2¶

Try three task types that should stay in plan mode:

Audit a config file for secrets
Review someone's code for style
Understand an unfamiliar codebase

Learn the judgment call.