Long live the plan

TL;DR

• Plan mode in coding agents has poor ergonomics. It doesn't help with brainstorming, specification, or understanding, because the read-only constraint means the agent can only speak to you through a streaming wall of text.
• When used well, plans capture some of the most important knowledge in your team. They compress a potentially long conversation leading to your product and technical design decisions. Plans should contain the why and not just the what.
• But plan mode loses that context. SageOx stores and cross-links plans as one of the many raw sources of team knowledge and makes them immediately available to every human and agent on your team.
• Planning shouldn't be done in isolation. Plans should be enhanced with your existing team context. SageOx plans are enriched with your team's context by searching your previous discussions, sessions, and decisions.
• But there is a weird dynamic between frontier models enabling long-horizon agents and the scoping of your plans. If you're not careful, you can fall into the waterfall.
• We're still learning the best way to create a fast "understanding" loop when building with our agents.

Understanding is a key activity in agentic development

Ayman Nadeem recently posted Plan mode is dead. I couldn't agree more. It's a great read and I'm on the same page with the spirit of most of what he writes, especially on the importance of designing a process that improves human understanding. Coding agents' UX does not help with that today. Hopefully, that will all change soon.

We've all been working around the limitations of our coding agents for months now. For me, it started in May when I couldn't understand Claude's analysis of a memory bug we were hitting while developing our hardware product, the OxDot (yeah, we'll have to rename it). The analysis resulted in a wall of text. At each turn, I had multiple questions, and I got another wall of text. Each round was a dizzying exercise of scrolling back up and trying to keep track of all the open questions. Then I saw an X post: The unreasonable effectiveness of HTML. So I asked Claude to generate a rich visual explanation of the bug. What I got back blew my mind.

Plan mode is actually worse

Then it dawned on me that my experience using plan mode was even worse. It's a read-only mode, and I'm forced to consume and scroll walls of text. Every question, comment, and new ask resulted in more indigestible walls of text. Exiting plan mode didn't help much. All I got back was a markdown file with limited typography, no use of color, and no visual aids. So, the very next day, I left plan mode and asked for an HTML plan instead.

It was immediately clear that richer typography, visual indicators, and clear callouts were vastly better. The chat window with the agent became, well, a chat window. And the HTML document became a dynamic surface that the agent updated instead of vomiting text.

Plans aren't just for planning, they're for understanding

Very quickly, the plans we created at SageOx stopped looking like detailed plans of intended code changes. Instead, they became documents that captured decisions, options, mockups, and most importantly the reasons why we landed on one option over another. As I went back and forth with the agent, it dutifully kept a record of our decisions and blind spots, and it would reorganize and update all the relevant parts of the document. One could reconstruct these decisions from our chat session (which we record automatically for any repo connected to SageOx). But the plan was essentially a distilled version of that agent "design" session.

To really understand, take a step back and see the big picture

Understanding the intent of a single problem or feature is not enough on its own. Good prompting and planning can drastically reduce how many tokens are required to get a working prototype out. But the highest-order bit is understanding the why behind what is being built. In most companies, that is tacit knowledge passed on through conversations. SageOx makes bringing that company knowledge into an agent's context at the right time (like when planning a feature) transparent.

It's even better if you share

At first, I leaned on SageOx to collate conversations and past decisions, generated context-rich plans as HTML, and committed them to our repo. But we quickly realized that because these plans were a distillation of decisions, they were some of the most important context in our team, for both humans and agents. These plans should be first-class context within SageOx itself. It was yet another virtuous cycle.

So we decided to make creating, enhancing, and sharing plans a first-class experience within SageOx. When you connect your repo to a SageOx team, we teach your agent about everything SageOx can do to help via our ox CLI.

The ox plan feature teaches a coding agent how to create truly great plans and walks it through the following:

• How to use SageOx to research the company's history to find previous conversations, discussions, coding sessions, and plans relevant to your current problem.
• How to raise the understandability of plans, by coaching it and giving it information design patterns for generating visualizations.
• How to render the plan in a separate, shared HTML workspace where you can comment, ask questions, and co-edit the plan with the agent.

When you're finished with your plan, your agent can publish it into your team context, and other coworkers can comment and provide additional feedback for posterity.

Because the plans are stored in your SageOx team context and not locked in your individual coding sessions, sharing plans between agents (even if they are different models or harnesses) is completely transparent. No need to copy and paste from one agent session to another. Want to continue where a prior plan left off? It's there; just have Claude start a derivative extension of that plan.

Planning can make waterfall development seductive

One really important insight from Ayman Nadeem's post is that planning can feel permanent. Because the horizon over which agents can work has gotten longer and longer, especially if you give them a good plan with clear objectives (mockups, acceptance criteria, etc.), it can be seductive to create bigger and bigger plans.

I've certainly fallen into this trap. At first it seems like a net positive. But more often than not, you don't have a complete idea of the right thing to build, and you need to iterate. This is where Ayman's cycle centered on understanding is absolutely correct. Recognize that you will have to do a new iteration on whatever you are building soon anyway.

The areas around whatever you are building are going to change rapidly as well. Even if you feel really great about something you built (something that would have stood the test of time for months or years in the BC era), the time to refactor and extend it is probably coming in weeks.

Here at SageOx, we're discovering where the balance is ourselves. We built the ox plan feature because we are building for ourselves. We're building the tools around a team context system to help AI-pilled builder companies like us build 40x faster.