The Spec Is a Working Agent

Building Companion, an AI assistant for the BigCommerce admin, and using the working prototype, not a document, to show the team how.

Case Study · 2026 · 8 min read

Companion is the AI assistant that lives inside a BigCommerce merchant's admin, the one that answers questions, finds things, and does the work the merchant would otherwise go clicking through a deep control panel to do by hand. My job here was not to ship it. My job was to stand in front of an engineering team and show them what this could be, and more importantly how to build it, and I have long believed that the most convincing way to do that is not a document. It is a working thing they can open, poke, and copy.

So I built one. And the first decision was the one everybody had an opinion about.

A prototype argues better than a spec

I could have written the spec. I have written plenty of them, and a good spec is worth its weight, but a spec asks a team to imagine the thing and then trust that your imagination and theirs line up. They rarely do. A prototype removes the imagining. You open it, you type into it, it answers, and now the conversation is about the real object in front of you instead of the one in the deck.

That is what I was really building. A reference. How to shape the system prompt so the model behaves like an assistant and not a chatbot, how to design a tool so the model can actually reach for it, how to split the work into smaller agents that each do one thing well. Lead by example, in the plainest sense of the phrase. Here is the machine, here is how it is wired, go build the real one.

No backend of ours

Here is the belief I wanted to knock down. Everyone knows an AI agent needs a backend. It needs a server somewhere to host the tools the model calls, an MCP server usually, something you build, deploy, secure, and pay to keep running. That is the shape of almost every agent you read about this year. So we would build one too, obviously.

Except a new browser capability had just shown up, WebMCP, and it quietly makes that whole layer optional. Instead of hosting the tools on a server, the page registers them on itself, on document.modelContext, and the agent discovers and calls them right there. The tools live where the merchant already is. So I put the catalog and the orders and the rest on the page, ran the model straight from the browser, streamed its events into the React UI, and that was it. No server of ours in the middle. The browser does the job the backend was going to do.

Do I think every production system should throw away its backend tomorrow? No. But the POC existed precisely to prove the tools can live on the page, and once the team sees that running, the questions change. Now we are talking about which capabilities belong on the page and how to design them, instead of how many weeks it takes to stand up and babysit a service. That, for a team about to build this for real, is the useful conversation.

The control panel is exhausting, and that is a design problem

Now to the part that is really product design and not plumbing. A BigCommerce admin is a big, capable, deep place, and the merchants who live in it are not confused by it. They know exactly where things are. What wears them down is the getting there. To change a sale price they open the product, scroll to the pricing section, find the field, edit it, save. To move an order along they drill into a status dropdown. To translate a description they hunt for the right locale, and to set a price for one storefront and not another they go looking for where that override even lives. None of it is hard. All of it is tiring, and that fatigue is a tax the merchant pays with attention they would rather spend on running the business.

I decided to treat that fatigue as the actual problem to solve, not a cosmetic one. If the merchant already knows what they want to change, the interface should not make them go and find the machinery to change it. They should be able to just say it.

The workspaces: say it, see it, save it

So the assistant grows a second surface when you need to edit something. Ask about a product or an order and a workspace opens beside the chat, the whole item laid out in one scrollable view, and now the chat is the input and the workspace is the live preview. You type "set the sale price to 19.99" and the workspace does not just do it silently, it shows you: the new value lit up, the old one struck through beside it, an unsaved changes badge sitting in the footer. Nothing is written until you press Save, and if you try to walk away with unsaved edits it stops and asks. Say it, see exactly what will happen, then commit it. The merchant stays in control the whole time, which for something driven by a model is not a nicety, it is the entire point.

The product workspace leans into the edits that are common and tiring in equal measure. A price tweak, a copy fix, and the two that are usually a scavenger hunt in the admin, translations and channel overrides. Here they are first class. You pick the storefront or the language you are working in, the editor re-renders in that scope, and it knows to write your edit to that channel's override or that locale's copy rather than the global product. The merchant does not have to remember where any of that lives. The editor already knows.

The order workspace does the same thing for the work fulfillment staff do all day. The whole order in one view, customer and addresses and line items and totals, and the move they make most, walking an order through its status pipeline, becomes a single sentence instead of a drill into a dropdown. Mark it shipped, fix a billing email, correct a shipping address, add a staff note. The routine ten-click errand collapses into one thing said out loud.

And here is the design decision I will defend hardest, because it is a decision about restraint. The workspaces do not try to swallow the admin. They deliberately do not rebuild the deep product editor with its variants and modifiers and custom fields, or the full order management screens, all of which are hardened and complicated for good reasons. When you ask for something structural the workspace says so plainly and hands you off to the real editor with an open-in-admin button. It takes the common, conversational, tiring edits and leaves the heavy machinery alone. A merchant who is not fighting the interface to do the routine things is a merchant with attention left over for the things that actually move their store, and buying them back that attention was the whole job.

The lightbulb: the model is the search engine

Then there is my favorite part, and it started as an annoyance. The control panel search is lexical. It matches the letters you type against the letters in the catalog, and that is all it does. A merchant does not think in letters. A merchant thinks "show me the cosy stuff for winter" or "the low stock I should reorder", and lexical search understands none of that. There is no semantic search in there to lean on.

And one day it just clicked. We do not have a semantic engine, but we have a model, and a model is a semantic engine if you point it the right way. So let it be the missing layer. The merchant says what they mean, the model grounds itself in the store's own vocabulary so it cannot go inventing words the catalog has never heard of, it fans that intent out into the keyword searches the documented API does understand, and then it reranks what comes back into an answer that matches what the person actually asked for.

The honest origin of the idea is that it was not a new idea at all. My brain had already done this once, translating plain language into SQL queries, and this was the same motion with a different target. Instead of writing SQL against a database, the agent writes the right calls against a documented API. Same bridge, different river. I ran it across a real catalog of four hundred and thirty eight products with a sweep of fourteen live queries to find where it lied to me, and then I fixed those, which is the part that never makes the demo but is the whole reason it works.

When the question is a total, not a product

Some questions are not "find me something". They are "how much did I make last month", "what are my top sellers", "how does this quarter compare to the last one". You cannot answer those by handing back product cards, because the answer is not a product, it is a number that lives across the whole store. Different question, different tool.

So the agent has a second surface underneath it: a Postgres database running inside the browser itself, a mirror of the store that fills and refreshes quietly from the same APIs. When a merchant asks an analytical question, the model writes SQL against that mirror, read-only and guarded so it cannot do anything careless, and when the answer is worth seeing rather than reading, it picks a chart and draws it. The nice part, for me, is that this data layer is a browser port of work I had already done on a separate analytics project. I did not build it twice. I moved it here.

The third world taught me the method

None of this was built and then admired from a distance. It has been in open beta for a good while, and the whole time I have been capturing evals, the thumbs and the trails of what the agent got right and where it fell down. I use those to generate detailed reports of what our merchants are actually asking and, more usefully, where they get frustrated. And the moment I see a gap turn into a trend, I do not file it, I jump straight into ideating and prototyping how to close it with the tools already sitting on the table.

I have a name for this, at least in my own head. I call it my third world mentality. I grew up in Venezuela, where the tool you need or the service you want is often simply not available, and you do not get to wait for it. You figure out how to make the thing work with whatever is in reach. That instinct never left me, and it turns out to be exactly the right instinct for this kind of work. No semantic search? The model is your search. No backend budget? The browser is your backend. You are not blocked, you are just being asked to be resourceful, and resourceful is a muscle I got to build early.

What it was really for

Companion goes generally available in the next couple of weeks, and the prototype I built is not the thing that ships, and it was never meant to be. It was meant to be an argument you can run. Here is an AI assistant with no backend of ours, a model standing in for the search the platform never had, workspaces that turn a tiring ten-click errand into one spoken sentence, a Postgres database living in a browser tab, all of it wired together and answering real questions on a real store. Look, it runs. Now let us go build the real one, and you already know how, because you have seen it work.

That is the version of leadership I trust most. Not telling people what is possible, but handing them something that is already doing it. And if you want to know the quiet joy under all of this, it is that so much of it lives in the browser again, in the front end, which is a story for another day. For now it is enough to say that the best spec I ever handed anyone was not a document at all, it was a working agent, and that, in my experience, is usually how it goes.