Diagram-driven development

I call it diagram-driven development. It started as a joke, the way "we should just rewrite it" starts as a joke. Then it quietly became how I ship every large feature.

The tool is planflow, a plugin I built for Claude Code and Codex. The pitch is one sentence: when a coding agent proposes a plan, don't read it as a wall of text and answer y/n. Render it as a flowchart in a browser window, edit it like a document, argue with it, and only then hit approve.

Why a diagram, of all things

Agent plans fail in a very specific way. The prose always reads fine. Step 3 sounds reasonable, step 5 sounds reasonable, and the fact that step 5 silently assumes a database migration that step 3 never does is invisible, because prose hides structure. A flowchart can't hide it. Dependencies become lines, parallel work becomes columns, and a missing edge is just visibly missing.

The editing matters more than the drawing, though. In planflow every field is editable before anything runs: rewrite a step, drag to reorder, delete the step where the agent invents a config system nobody asked for. You can comment on a single step and the agent replies in place, like a code review that happens before the code. Every decision lands in .claude/plans/, so there's a paper trail of what was approved and why.

And because I know the first question every engineer asks about a browser approval window: everything runs locally on a loopback port, with host-header validation, a per-approval secret, and a strict CSP. Nothing leaves your machine. The UI is a single HTML file, React Flow loaded from esm.sh, no build step. Paranoia and laziness, working together.

Where it earns its keep

For a small fix, this is ceremony, and I skip it. The payoff curve bends hard at the size where a plan stops fitting in your head: the billing migration, the auth rework, the feature that touches nineteen files across three services.

On features like that, my old workflow was to skim the agent's plan, say yes, and then discover the wrong assumption forty minutes into execution, usually as a diff I now had to unwind. The plan review moves that discovery to minute two, when the wrong assumption is a box I can rewrite instead of a branch I have to revert. I've stopped being nervous about pointing an agent at large-scale work, not because the agents got perfect, but because "inspect the plan, then greenlight it" is the same trust ritual I'd give a new teammate.

The name of the game isn't control. It's that a good diagram is the cheapest possible place to be wrong.

Try it

claude plugin marketplace add davejj1530/planflow-greenlight

claude plugin install planflow@planflow

Then ask for a plan and type /planflow. Draw first, code second. I'm mostly kidding about the methodology name. Mostly.