spec-commerce

Turn building and product specifications into bill-of-materials transactions online.

Comment

3-Second Version

The easiest way for humans and agents to turn complex building and product specifications into purchasable bills of materials for large construction or infrastructure projects.

Inspiration

I co-founded and operate US Made Supply, a headless B2B e-commerce business built on Shopify. We domestically source compliance driven products including specialty fire extinguishers, cabinets and other code-driven building products.

A lot of what we sell is tied to building specifications or codes, especially on complex projects like fab factories or data centers. The hard part is not just finding a product. It is figuring out which exact products and combinations of products match the specifications, drawings, engineering requirements and building codes. You also need to figure out the right quantities. I recently had to do this on a large project and it took many hours of tedious effort.

The process today is still very manual. Someone has to read the specs, understand what is required and what the relevant building codes are, compare it against manufacturer product data, talk to manufacturer reps, review plan detail sheets, build the bill of materials and then turn that into a quote or order.

AI agents can help read and reason through these documents but still have a hard time selecting and transacting on the right product combinations. Hallucinations are commonplace.

That is the idea behind our spec-commerce prototype. We want to give agents the tools to turn building specifications into bill of materials transactions online. The global building and construction products market is over $2T USD today (just because this needs the usual mandatory ambitious market data!)

What it does

Helps agents turn complex building specifications and plans into bills of materials for construction projects. We are starting with fire life safety products.

It is one script tag on a product page. The tag adds a small panel and registers six tools that an AI agent in the browser can use. The agent reads the customer's spec and passes the requirements to the page. The page checks them against product data, where every value has the cut sheet or product page it came from, and answers in plain words: this product meets the spec or it does not, here is why, and here is what on the site does. The agent can propose lines for a quote request. Only a person can approve them, on the page. There is no tool that can approve.

The page never guesses. If a requirement cannot be checked from product data, it says so instead of rounding up.

Why WebMCP

A customer buying against a spec shows up with a stack of documents. The specification says what the product has to be. The schedule says how many go where. The plan detail sheets show how they mount. The building code sits behind all of it. Then there is the manufacturer's cut sheet, which is where the actual numbers live. An agent is good at reading that stack. It can pull the requirements out of section 2.3, find the quantities on schedule A-601 and keep the code citations straight. The three demo documents in the repo are exactly that stack: a spec excerpt, a schedule sheet and code citations.

What the agent cannot do is the last step. Landing on a product page, it has to read the page like a person and guess. It cannot reliably tell whether the product in front of it meets the spec, or which other product does, and it makes things up when it is not sure. That is the wrong place to guess. A fire extinguisher rating is a fact on a cut sheet, and whether a cabinet fits is a matter of inches.

WebMCP lets the merchant's own page answer those questions. The store already knows its products, the values on the cut sheets, and which cabinet fits which extinguisher. With WebMCP those facts become tools the agent can call on the page, in the browser the customer is already using. The agent reads the documents and brings the requirements to the page. The page checks them against product data and shows where each value came from. Quantities come from the schedule, never from the spec, and the page keeps that straight too. The agent does not scrape or guess. The store does not build an API or run a server. The customer sees every answer on the page they are looking at, with the source next to it.

What people and agents do together

Before this, a person read the spec, looked up the products, checked the numbers, built the bill of materials and wrote the quote. It took hours and it was easy to get wrong. An agent on its own could read the spec but could not be trusted with the rest.

Now the work splits by who is good at it. The agent reads the spec and asks the page the questions. The page checks the facts and shows its sources. The person decides. The agent proposes lines, and the person approves each one, changes a quantity, or rejects it with a reason, right on the page. The agent reads those decisions back and carries on. Nothing is ordered without a click from a person, and there is no tool that can make that click.

How I built it

The whole thing is one script tag. The bundle reads the product from the page's JSON-LD, mounts a launcher and a panel in its own shadow DOM so nothing on the page moves and registers six tools with document.modelContext.registerTool(). This also allows us to add the functionality selectively to pages and also create a multi-tenant system into the future.

The six tools:

  • resolve_requirements takes a spec clause as written, or a list of requirements, and answers what in the catalog satisfies it. It understands a basis of design, numbered alternates and two-unit combinations.
  • get_product returns this product's facts, each with its source. Read only.
  • check_requirements checks this product against requirements, one row at a time, with the evidence.
  • find_compatible finds cabinets that physically fit this extinguisher, or the reverse, with the clearance in inches.
  • add_to_quote_request proposes lines and waits for the person to click Approve or Reject on the page. It returns their decisions, their reasons and their notes.
  • get_quote_request returns the approved lines with indicative prices. Nothing is ever submitted from the page.

Underneath, the code is in layers. The core is plain TypeScript with no browser in it: the requirement language, the comparators, the class rating math, the cabinet fit geometry, the catalog resolver, the spec reader and the quote request. One adapter per merchant holds the catalog snapshot, every value with its source. Every change to state goes through one set of commands, and the panel and the tools call the same commands, so the agent can never do anything the person could not do by hand. The tools are validated contracts over those commands, and a thin adapter turns them into WebMCP registrations. The panel is React in a shadow root.

Matching is deterministic; there is no model in the compliance path. Unknown is a real answer and is never rounded up. An agent may propose; only a person may approve. Quantities never cite the specification as their source, because specs do not carry quantities. Right now we're keeping it pretty simple and there is no server, no database, no API key etc. The small catalog is a committed snapshot and state lives in the tab.

It runs in the ChatGPT desktop app's browser in Work mode and in Chrome 149 or newer with the WebMCP flag on. Hosting is Cloudflare and our main site(s) also uses Cloudflare infra. The demo page mirrors our real product page and pins the exact bundle version. Actual demo can be seen in production at: https://usmadesupply.com/safety/fire-extinguishers/halotron/usms-marketplace/products/buckeye-11-lb-halotron-clean-agent-fire-extinguisher?spec-commerce

What I learned

Most of the surprises were about how agents hand things to a page. In ChatGPT, Chat mode reads pages but does not use site tools; Work mode does. A file attached to the chat stays in the chat and is not handed to a site's tools, but pasted text is. If "Approve for me" is on, the agent may decline on your behalf.

What's next for spec-commerce

We want to support more product categories and more of the construction workflow. Longer term this could plug into CAD, estimating, procurement and other software used by engineers, architects, contractors and distributors. Maybe over time, smaller models tuned specifically for this kind of work could also make sense.

Built With

Share this project:

Updates

Submission history