Planning

What we just did in the previous sections, letting the agent have full control of a multi-step process, is not the best way to fully leverage agentic coding capabilities. Instead, it is recommended to break down your workflow into smaller, distinct increments that are easier to verify and iterate on.

Plan mode overview

While it is easy to think of Plan mode merely as a “read-only” or Q&A mode, its primary goal is actually to develop a highly refined prompt—aka. the plan—that will guide the agent during actual implementation.

The structure and quality of this plan depend on several factors, for example:

The agent tool: The structure of the plan is defined by the underlying tool or “harness” guiding the agent. Two different harnesses can produce substantially different plans from the same initial prompt.
The Model: The quality of the resulting plan is closely tied to the model you use. While a frontier (most advanced) model doesn’t strictly guarantee a better prompt, the chances of generating a comprehensive, well-reasoned plan are much higher.
Your Instructions: The prompt you send during the planning phase is critical. More detailed instructions and context lead to a better, more accurate plan.

To effectively integrate agentic AI into your work, consider following this structured approach:

Begin in Plan mode (read-only)
Review the proposed steps for your analysis
Supply additional context and refine the plan
Iterate through this cycle as many times as needed
Ask for separate scripts for the primary components of your workflow
Once satisfied, switch to Build mode for actual implementation
Leverage version control to create snapshots of your work before and after major changes

Best Practices for Planning and Execution

A good practice is to reserve the plan for specific tasks, bug fixes, or new features, rathen than attempting to plan out a massive, open-ended project all at once.

Similarly, it is advisable to implement the plan incrementally, verifying each step, task or phase before proceeding to the next. This approach allows for early detection of issues, and keep each step in a separate, manageable context. It also allows for more effective use of version control, as each step can be committed and reviewed independently.

When reviewing the plan, you might consider questions such as:

Does the plan reveal gaps in your understanding that need to be resolved before moving ahead? If you read the plan and think to yourself, “Wow, this is more complicated than I imagined!”, then this might be the case. You might want to cancel the plan or rethink your approach.
Does the plan resolve ambiguities in the initial prompt in ways that align with your expectations? If not, update the plan with additional specificity.
Does the plan make appropriate implementation choices (programming language, dependencies, data sources, etc.)? You may need to steer the coding agent toward tools and approaches you prefer.

Switching to plan mode

In OpenCode, you can use the tab key to switch between Plan and Build modes. Build mode is the default when you start OpenCode. The active mode appears right below the cursor in the prompt input area.

Models for Planning

After toggling between modes, always check which model you are using, as Plan and Build modes can use different models. You can sometimes save money/tokens by planning with a larger, more expensive model and then implementing with a smaller one. For the purposes of this workshop, we will use Gemini 3.8 Flash for both planning and code generation.

Planning our NOAA tides example

Let’s revisit the California tides analysis from the previous lesson and see what it would be like to generate this code using planning mode. (Since you already generated this code, you don’t need to follow the steps here. This is just a demonstration of Plan mode).

To use Plan mode:

Start OpenCode in the noaa-tides project folder. If you have an existing OpenCode session, start a new OpenCode session with /new.
Switch to Plan mode by pressing the tab key until you see “Plan” below the text input cursor.
Select your planning model with the /models command and choose the Gemini 3.8 Flash model.

To kick off the planning process, let’s begin with a plan to refactor the download logic for the NOAA tides data, ensuring it aligns with the structure described in our AGENTS.md file.

You can start with a prompt like this (be sure to replace [name_of_your_script.py] with your actual file name):

I would like to refactor our Python script that downloads the monthly mean high water for California NOAA stations.

The current download logic is in [name_of_your_script.py]. Please review the code and propose a plan to improve it. Use the AGENTS.md file as a reference for project structure, coding conventions, and workflow guidelines. Please include any missing details or clarifying questions needed to ensure a successful implementation before we begin.

During the development of the plan, you may find that the agent asks for additional information or clarification. The agent will typically include these questions at the end of its proposed plan. The following is an example of what the agent might ask:

## Clarifying Questions & Design Choices

Before proceeding with the refactoring, please clarify your preferences on the following:

1. **File Locations & Entrypoints**:
   - Would you like your Python scripts moved to `code/` (e.g., `code/download.py`), or should they remain at the root as entrypoints?
2. **Data Output Destination**:
   - Should the output be directed to `data/data-raw/ca_monthly_mean_high_water_10yrs.csv` per the `AGENTS.md` file? (If so, should `plot_tides.py` be updated to match, while maintaining backward-compatibility fallback?)

Caution

The plan can be implemented without addressing these questions, but it is highly recommended to answer them to reduce the risk of misalignment between your expectations and the agent’s implementation.

Also, it is okay to tell the agent that you are not sure how to address a question or that you don’t have a preference. The agent can provide suggestions and recommendations based on best practices.

The plan looks fine – isn’t it useful to see what the agent would do before it does it? We’re ready to build:

Switch to Build mode by pressing the tab key
Enter a prompt to kick off the build process, explicitly requesting that the plan be saved first: “The plan looks good. Before implementing any code, please save this plan to .opencode/plans/noaa-refactor-plan.md. Once saved, go ahead and implement it!”

That’s it. Now it’s your turn to try Plan mode.

Challenge: Enhancing your Code

As before, please complete this exercise individually but discuss issues and results in small groups (2-5 people).

Perhaps you’ve noticed that downloading data using the default STND datum provides data relative to a local station datum, which makes it difficult to compare water levels across different locations. Also, depending on how your code was generated, you might be downloading the MHW (Mean High Water) product, or a mix of metrics. Let’s use Plan mode to refactor the script to explicitly use a standardized vertical datum:

Make sure you are running OpenCode in the noaa-tides folder. If you have an existing OpenCode session, start a new OpenCode session with /new.
Enter Plan mode and make sure you are using Gemini 3.8 Flash.
Make a plan to refactor your code. You can use a prompt like this: “Refactor our existing download script so that it explicitly fetches the MHW (Mean High Water) product for the last decade using the MLLW datum as the vertical reference and the metric system for units. Ensure the updated script and its data outputs strictly comply with the directory structure and conventions defined in AGENTS.md.”
Inspect the resulting plan and answer any clarifying questions the agent might ask.
Iterate on the plan if needed (e.g., you can ask the agent to add a reorganization of your files, moving plots to an output folder).
Switch to build mode.
Kick off the build process by explicitly asking the agent to save the plan first: “Looks great. Before doing anything else, save this plan to .opencode/plans/mllw-refactor.md. Then go ahead and execute it.”
Validate your changes by running the script from your terminal (e.g., uv run code/download.py) to ensure the data is fetched and formatted correctly.
Ask the agent to generate a README.md file with a minimal description of the project and basic instructions on how to run the code.
Make sure you commit your work (the refactored code, the saved plan, and the new README). You can even ask the agent to help you write the commit message!

Explore further

A few ideas:

Refactor your code to generate separate CSV files for each datum.
Select a single station and analyze changes across different years.
Create an interactive data visualization using Plotly.
Explore NOAA metadata to know what type of information is available for stations? For example, could we get latitude/longitude to make a map?

Session management

In the exercise above, we started Plan mode from a new session, which we create with the /new command. A session is a single, continuous conversation with the coding agent: your prompts, the agent’s replies, and every file it read or wrote along the way. Everything in the session makes up the agent’s context – the information it carries with it from one prompt to the next. That’s why the agent “remembers” the datum and the units you specified ten prompts ago.

Warning

Long session gets slower and more expensive: the entire conversation is sent to the model each time you hit Enter.

Sessions are saved to disk, so quitting OpenCode doesn’t throw yours away. To pick up where you left off:

Run opencode --continue (or opencode -c) to reopen the most recent session in the current project folder.
Or start OpenCode normally and use the /sessions command to list your past sessions and select the one you want.

Resuming is useful when you’re returning to a task you left half-finished, like a very detailed planning session. Starting fresh with /new is usually the better choice when you switch to a new task, when the agent seems confused or keeps circling back to earlier (now-irrelevant) decisions, or when the session has simply grown long. A clean context is cheaper, faster, and easier for the model to work with.

This connects directly to Plan mode. Planning is a conversation: you brainstorm, ask questions, change your mind, and reject a few approaches before settling on one. All of that dead-end discussion stays in the context when you switch to Build mode. If your planning session runs long or eats a lot of context, a good practice is to ask the agent to write the plan to a markdown file (for example, plan.md or docs/plan-uv-migration.md), then start a new session with /new and prompt the agent to implement the plan from that file.

Saving and committing your plans into your version control repository is also excellent for reproducibility. These markdown files serve as living documentation that helps you (and your collaborators) understand the specific decisions and actions that affected the codebase over time.