anmandu

Plan Before Code: Field Notes on Opencode and SDD

Most people install an AI coding agent, type "build me a dashboard," and then spend the next three hours explaining to it what they actually meant. That is not engineering. That is negotiating with a slot machine.

These are my working notes from setting up opencode and pushing it into a spec-driven workflow instead of a vibe-coding one.

Getting started

Install opencode, open a terminal, and drop into a folder that will be your workspace. The agent inherits the context of wherever you launch it, so the folder choice is not cosmetic — it is the boundary of everything the model can see.

Then check which models you have:

/models

There are free models available out of the box, which makes this a cheap place to experiment before you commit budget to anything.

The two modes, and why the choice matters

Press Tab to toggle between the two modes:

  • Plan — the agent produces steps. It thinks, decomposes, and proposes. It does not go rewrite your repo behind your back.
  • Build — the agent writes code.

Here is the part worth internalizing: build mode alone does not scale. It is vibe coding. It works beautifully for a toy, and it falls apart the moment the change touches four files, two conventions, and one thing you forgot to mention. The failure is not the model's — it is that you handed it an under-specified problem and hoped.

Plan mode is where the leverage lives. You spend tokens on understanding before you spend them on typing.

A workflow that actually holds up

The pattern I keep coming back to is: write the artifacts first, let the agent implement against them. Concretely, four prompts in plan mode:

Create design as DESIGN.md
Create the PRD (product requirement document) as PRD.md
Create a plan based on the PRD as PLAN.md

Then execute the plan with a spec-driven implementer.

Each file has a job. DESIGN.md captures the shape of the thing. PRD.md captures what it must do and for whom. PLAN.md is the ordered set of steps that gets you from here to there. By the time the agent starts writing code, the ambiguity has already been argued out in markdown — which is a much cheaper place to be wrong than in a diff.

This is the same reason we write architecture docs for human teams. The agent didn't change the fundamentals. It just made skipping them feel affordable.

Spec-driven implementers worth looking at

Once you have the plan, you need something that executes it phase by phase rather than in one heroic shot. Options in this space:

  • gentle ai
  • OpenSpec
  • Spec Kit
  • Claude superpowers
  • GSD (Get Shit Done)

They differ in ceremony and opinionation, but they share the core idea: the spec is the source of truth, and implementation is a derivative of it.

Keep the human in the loop

Two habits that turn this from a demo into a practice:

  • Authorize each phase. Do not hand over a blanket approval for the whole plan. Review the boundary between phases — that is where drift starts, and that is where it is cheapest to fix.
  • Watch the sub-agents. Ctrl + X surfaces the sub-agents during execution. If you cannot see what is running, you cannot review it, and "the AI did it" is not a code review.

The human leads. The model executes. Invert that and you are just generating technical debt at a higher throughput.

OpenRouter

OpenRouter gives you a large catalog of curated models behind one interface. Useful for the same reason a good bundler config is useful: you decouple the choice of engine from the rest of your setup, and you can swap models per task — a cheap one for mechanical edits, a strong one for design work — without rebuilding your workflow.

Open questions

Still on my list to test:

  • Ollama + opencode. Running local models through this workflow. Latency and quality tradeoffs are the obvious question; whether plan mode stays useful on a smaller local model is the interesting one.
  • Engram. Persistent memory across sessions — worth evaluating against how much context the DESIGN.md / PRD.md / PLAN.md triad already carries on its own.

The takeaway

The tool is not the point. The discipline is. opencode's plan mode is valuable precisely because it forces the step most people want to skip — deciding what you are building before you build it.

Concepts before code. Every time.