{"slug": "introducing-visual-plan-scannable-claude-code-plans", "title": "Introducing /visual-plan: Scannable Claude Code plans", "summary": "Builder.io introduced /visual-plan and /visual-recap, two skills that bring structured, scannable plans to Claude Code agent workflows, addressing the risk of unreviewed probabilistic code generation. The company argues that treating agent plans as source code and the agent as a non-deterministic compiler creates a human context gap, where users approve massive code changes without proper visibility. The visual-plan skill provides a semantic interface—showing wireframes, API shapes, or UI states—to let developers verify intent before execution.", "body_md": "# Introducing /visual-plan: Scannable Claude Code plans\n\n[AI](/blog/topics/ai)\n\nYou run a command and watch the agent draft a clean-looking plan. You greenlight the execution, step away for coffee, and return twenty unsupervised minutes later to find a 4,000-line pull request spanning 40 different files.\n\nYour job just shifted from creative builder to exhausted code reviewer who can’t feasibly review everything line by line.\n\nWe've been building toward a practical answer: two skills called `visual-plan`\n\nand `visual-recap`\n\n(plus the open-source framework to support them) that bring structure and a verifiable contract back to the runtime.\n\n[You can ask your agent to drop them into your workflow today](https://github.com/BuilderIO/skills), and you don't need to know anything else.\n\nBut if you're interested in the structural reasons why we built them, read on.\n\nIn this shift from writing code to auditing it, we've crossed an architectural line without naming it: we've started treating the plan as source code and the agent as the compiler. Just like we stopped reading assembly once we trusted C, we've stopped reading the actual code.\n\nThis makes your taste and your judgment the ultimate bottleneck. But it also introduces a massive risk.\n\nBecause C compilers are deterministic. Compile the same C twice, you get the same binary. But hand the same plan to an LLM twice, and you get two completely different codebases: different patterns, different dependencies, and different bugs.\n\nOur new compiler is probabilistic. It will place an auth guard on the wrong side of a boundary, generate an unnecessary database column, and degrade a core query—all with absolute confidence. When you skim a massive markdown file and hit approve, you aren't blessing a plan. You're signing off on an uncompiled, unpredictable binary. We're shipping the largest volume of unreviewed, non-deterministic assembly in history, and we're calling it velocity.\n\nTo stop shipping blind binaries, we have to change how we interact with these loops.\n\nIf you watch how these tools operate, they address a massive asymmetry in how we build agentic systems. We pour endless effort into optimizing the machine's context: building MCP servers, vector pipelines, and tightly pruned token windows. But look at what we send back to the human: three screens of unformatted terminal logs.\n\n| Machine Context (Obsessively Optimized) | Human Context (An Afterthought) |\nStructured tools and schemas | Three screens of raw markdown |\nPruned, relevant token windows | Ephemeral terminal logs |\nAn indexed, retrievable repo | Cognitive skimming |\n\nYour judgment is the most expensive resource in an autonomous loop. Starving your own context is a massive bottleneck. Human eyes aren't built to spot an architectural flaw in a wall of sequential terminal output. A missing loading state, a leaked database relation, or a duplicate component built from scratch—you'd catch these in a second if you *saw* them.\n\nBut a wall of text is hostile. Your eyes glaze over, you hit enter to approve, and you spend the next hour debugging what you could have caught in three seconds if the format had been better.\n\nThis context gap completely changes how we have to approach the planning phase. If the agent is going to write all the code, and we’re not really going to change it directly, then you have to verify the agent’s intent before it starts. Because of that, a plan needs to act as an official contract. You aren't reviewing code; you’re acting as the runtime validator for a chaotic compiler.\n\nThis is what `visual-plan`\n\nactually is: a semantic interface for verifying a probabilistic compile. A visual plan—showing the actual wireframe, the real shape of the API, or how an empty list state renders—lets you catch alignment issues before the agent writes a single line of code. It shifts your role from babysitting a terminal to steering with intent.\n\nBut for a contract to hold, it can't be written in slippery, freeform prose. That's why these plans use MDX instead of standard markdown. It's not for decoration; it's for schema enforcement.\n\nFreeform text has infinite entropy. Left to itself, an agent will wander, omit critical details, or hallucinate schemas. By forcing the agent to output typed UI components, we build a playground with strict walls. A `<DataModel>`\n\nblock must declare keys and relations. An `<Endpoint>`\n\nblock must explicitly define its auth strategy. The agent can no longer hide a missing guard behind confident prose; it either fills out the schema or leaves it conspicuously blank. This is type-safety for natural language.\n\nIt's [generative UI](https://www.builder.io/blog/designing-generative-ui-in-an-agent-native-world) in the developer loop. The agent assembles real, design-system-compliant primitives instead of hallucinating raw markdown. Plans from different models read like they were written by the same engineer. And because these plans are actual MDX files checked into your Git history, they don’t have to be ephemeral. They’re versioned, collaborative contracts you can comment on, redline, and edit directly.\n\nSecuring the upstream contract is only half the battle. You still have to verify the delivery at the other end of the loop. That's where our traditional tools break down.\n\nFor twenty years, the Git diff and the pull request have been our primary governance tools. But when an agent drops 4,000 lines of code into a branch, line-by-line review breaks down. We can't audit at the line level anymore. We have to audit at the contract level: *did the agent build what we agreed to in the plan, and only that?*\n\n`visual-recap`\n\nsolves this. Instead of a vague markdown summary or an unreadable 3,000-line diff, it lifts the changes back into the components defined in the plan. It exposes the real schema changes, the endpoints modified, and the UI states introduced.\n\nNow, governance is simple: do the plan and the recap align? If they drift, the build is broken, even if the test suite passes. Because they share a structured schema, we can run an agent to flag the drift automatically, letting you focus your attention on the only question that requires a human: *was this drift a smart pivot or a hallucination?*\n\nA recap is still a generated summary, so it earns trust the way a summary has to: it's generated from the actual PR or branch diff, not the agent's say-so, and it points straight at the ground truth—the changed lines and the deployed preview. Read the recap to know where to look; click through to confirm.\n\nWhen you step back and look at this entire lifecycle, from structured plan to verified recap, you realize the whole shape of our job has shifted.\n\nWe've spent two years treating prompt engineering like a master craft—writing longer instructions, expanding context windows, and refining system prompts. But you don't steer an autonomous agent by prompting it louder. You steer it by [engineering the environment](https://www.builder.io/blog/how-to-make-ai-agents-follow-your-design-system): schemas, types, AST-level linter rules, and visual contracts. Code generation is solved; constraint engineering is the new bottleneck.\n\n| Writing Code | Designing Systems (Constraint Engineering) |\nHand-writing syntax | Engineering deterministic constraints |\nAuditing line-by-line diffs | Auditing high-level visual contracts |\nBabysitting terminal state | Commanding sandboxed execution loops |\n\nThe right-hand column is what we can't automate. Someone still has to decide if the system being built is the right system, shaped the right way. That is taste. It's our scarcest resource, and you can only apply it as well as your interfaces allow. If we keep giving humans three screens of markdown, we're starving the only part of the loop that doesn't scale.\n\nThis shift from prompt tuning to environment design isn't just a footnote about better tooling. It's the next logical step in how we build with agents. First, we isolated execution so a runaway loop couldn't brick your machine ([worktrees, containers, sandboxes](https://www.builder.io/blog/ai-agent-orchestration)). Now, we are isolating human attention so the loop's output doesn't drown us (structured, component-driven plans and recaps instead of walls of text).\n\n[Agent Experience (AX)](https://www.builder.io/blog/agent-experience) is becoming a strict branch of systems engineering. The interface between human and agent is now core infrastructure. It’s just as critical as your type system or test suite.\n\nThis model isn't for every task. When you're actively pairing with an agent, iterating on UI, or experimenting with code, a heavy planning phase just slows you down. But for autonomous, long-running execution loops, a structured plan is your only lever for control.\n\nAgents will keep getting better at writing code; that's a safe bet. The bottleneck is moving entirely to you—your judgment, and whether you have the visibility to exercise it. Stop squinting at terminal scrollback and give yourself an interface built for the job.\n\nFind more of our [open-source, agent-native tooling here](https://agent-native.com/).", "url": "https://wpnews.pro/news/introducing-visual-plan-scannable-claude-code-plans", "canonical_source": "https://www.builder.io/blog/claude-code-plan", "published_at": "2026-06-24 18:00:00+00:00", "updated_at": "2026-07-22 23:07:59.477692+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "generative-ai"], "entities": ["Builder.io", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/introducing-visual-plan-scannable-claude-code-plans", "markdown": "https://wpnews.pro/news/introducing-visual-plan-scannable-claude-code-plans.md", "text": "https://wpnews.pro/news/introducing-visual-plan-scannable-claude-code-plans.txt", "jsonld": "https://wpnews.pro/news/introducing-visual-plan-scannable-claude-code-plans.jsonld"}}