# The blueprint is the source

> I set out to compile docs from a codebase, and ended up questioning whether code should be the source at all, or whether agents will turn blueprints and primitives into the real source.

I set out to compile docs from a codebase, and ended up questioning whether code should be the source at all.

## Where it started

I have worked on codebases that span frontend and backend, held together by glue such as the [T3 Stack](https://create.t3.gg), [tRPC](https://trpc.io), [Hono](https://hono.dev) with [drizzle-zod](https://orm.drizzle.team/docs/zod), and more recently [Effect](https://effect.website) v4. Much of the reason these exist is to carry the backend's source of truth to the frontend that consumes it, with type safety and runtime validation that catch drift early.

Public documentation follows the same principle: derive every downstream view from **one source of truth**, so nothing has to be maintained twice. Docs generated from code can be tailored to serve both public and internal readers, yet I think they could do far more to help engineers and agents understand a codebase and move through it efficiently. So I began to wonder: what if there were a tool that feels alive and dynamic, yet is derived entirely from the codebase it runs on?

My first answer was a better doc generator: one that scans the whole codebase, parses it, compiles functions and documentation recursively, and works out how everything is wired together.

I tried this on several of my projects: TypeScript, React Native, monorepos with modules, native code, web and backend. It proved extremely difficult, if not impossible, for static analysis[^1] to understand all of that at once.

A config file seemed like a way out. But the point of the tool is to compile directly from the source, and a config file is one more layer that can drift or be forgotten as new things are added to the repository.

## Drift, even with agents

These repositories are already agent-run. Agents write the code, update the docs in the same commit, and run gates on every change. Stale references still slip through: 1 of about 45 code references in this site's `AGENTS.md`, and 3 of 176 path references in [UT Companion](https://apps.apple.com/us/app/ut-companion/id6761080156), one of which stayed wrong for 77 days.

*Picture: A timeline of one stale path in UT Companion. A file moved on 21 June 2026, and the doc that named its old place was fixed on 6 September: 77 days and 113 commits later. The commits fall on nine days, 61 of them on one day in July, and none of them caught it.*

The drift that costs most is semantic drift[^2]: a server and a client that disagree on what `totalSpaces` means, or a README that recommends `npm` where `AGENTS.md` forbids it.

It gets worse with size. If a repository grows ten or twenty times, keeping every doc and function aligned costs that many more tokens.

That cost led me to an intermediate idea, while I was still treating code as the source: for functions and classes, what if their human-readable descriptions were not stored at all? **A description that is not stored cannot go stale.** An agent would write one on demand, only when someone wants to know more. Everything else, the comments and the code itself, could then be written for agents first. That solved stale prose on individual functions, but it did not explain the whole shape of a repository.

## One codebase, many views

Tools that derive docs from code already exist. I ran TypeDoc, react-docgen-typescript and scip-typescript on two of my repositories, and on a repository set up the way they expect, they work well. But none of them reads a stylesheet, a design token, a Figma file, the meaning of a route file or a glossary: the part that is particular to one repository.

So the first half of my vision is a layer that covers that part too: documentation, visualizations and isolated previews of the frontend, derived from the source and the designs, and kept current by agents.

What it makes possible is that **every team reads the same codebase in the language it understands**, laid out the way it works. Take a payment flow. A designer cares where the cart, checkout, confirmation, failure and order detail screens go. Marketing and sales care about pricing and offers, the funnel and what is tracked. Developers care about the logic they own. Each reads the same plain-language blueprint of the flow from its own side, and each can suggest a change that an agent understands and carries out against the code.

*Picture: one payment flow of five steps, read four ways. Designer, as screens: Cart: A sheet over the shop page. Checkout: Full screen, three fields. Confirmation: Takes the place of checkout. Failure: Stays on checkout, card marked. Order detail: One page per order, in Account. Marketing and sales, as a funnel: Cart: 1,000 carts, Offer: 10% off a first order. Checkout: 620, Step 2 of 3 · tracked. Confirmation: 480 orders, Conversion · 48%. Failure: 70, Drop-off · card declined. Order detail: 28%, Reorder within 90 days · no offer. Developer, as the plain-language blueprint, and the agent, as the Effect code underneath.*

```jsx
<Flow name="Payment">
  <Step name="Cart">
    <Design>A sheet over the shop page</Design>
    <Sales>First-order offer: 10% off</Sales>
    <Logic>Total is items less discount</Logic>
  </Step>
  <Step name="Checkout">
    <Design>Full screen, three fields</Design>
    <Sales>Funnel step 2 of 3, tracked</Sales>
    <Logic>Charges once, safe to retry</Logic>
  </Step>
  <Step name="Confirmation">
    <Design>Takes the place of checkout</Design>
    <Sales>Counts as a conversion</Sales>
    <Logic>Saves order, queues receipt</Logic>
  </Step>
  <Branch name="Failure" from="Checkout">
    <Design>Stays on checkout, card marked</Design>
    <Sales>A drop-off, with its reason</Sales>
    <Logic>Card declined, stock released</Logic>
  </Branch>
  <Step name="Order detail">
    <Design>One page per order, in Account</Design>
    <Sales>No offer is shown here</Sales>
    <Logic>Reads one order by its id</Logic>
  </Step>
</Flow>
```

```ts
import { Context, Data, Effect, Layer } from "effect"
import type { Card, Cart, Charge, Money, Order, OrderId } from "./model"
import { OrdersLive, PaymentsLive, ReceiptsLive, StockLive } from "./live"
import { Screen } from "./screens"

// Failure: the card is declined, and says why.
class CardDeclined extends Data.TaggedError("CardDeclined")<{
  readonly reason: string
}> {}

class Payments extends Context.Service<Payments, {
  readonly charge: (card: Card, total: Money, key: string) =>
    Effect.Effect<Charge, CardDeclined>
}>()("Payments") {}

class Orders extends Context.Service<Orders, {
  readonly save: (cart: Cart, charge: Charge) => Effect.Effect<Order>
  readonly byId: (id: OrderId) => Effect.Effect<Order>
}>()("Orders") {}

class Stock extends Context.Service<Stock, {
  readonly release: (cart: Cart) => Effect.Effect<void>
}>()("Stock") {}

class Receipts extends Context.Service<Receipts, {
  readonly queue: (order: Order) => Effect.Effect<void>
}>()("Receipts") {}

// Cart: the total is the items less the discount.
const total = (cart: Cart) => cart.subtotal - cart.discount

// Checkout: one charge, keyed by the cart, so a retry is safe.
export const checkout = Effect.fn("checkout")(function* (cart: Cart, card: Card) {
  const payments = yield* Payments
  const orders = yield* Orders
  const receipts = yield* Receipts
  const stock = yield* Stock
  return yield* payments.charge(card, total(cart), cart.id).pipe(
    // Confirmation: save the order and queue its receipt.
    Effect.flatMap((charge) => orders.save(cart, charge)),
    Effect.tap((order) => receipts.queue(order)),
    Effect.map((order) => Screen.Confirmation({ order })),
    // Failure: release the stock and stay on checkout.
    Effect.catchTag("CardDeclined", (e) =>
      stock.release(cart).pipe(
        Effect.as(Screen.Checkout({ cart, marked: "card", reason: e.reason }))
      )
    )
  )
})

// Order detail: one order, read by its id.
export const orderDetail = Effect.fn("orderDetail")(function* (id: OrderId) {
  const orders = yield* Orders
  return yield* orders.byId(id)
})

// What the flow needs, provided once.
export const PaymentFlow = Layer.mergeAll(
  PaymentsLive,
  OrdersLive,
  StockLive,
  ReceiptsLive
)
```

## Primitives, not platforms

The other half of the vision is how that layer itself is built. Code is now cheap. [Theo Browne argues](https://www.youtube.com/watch?v=28z6OjsNsUk) that generating lines of code is virtually free, and that the engineering value lies in verification, infrastructure and keeping software correct. So I don't think the old shape, one software core with adapters and plugins around it, is the right way to build this. I picture an ecosystem instead, like shadcn/ui but for lower-level code: small chunks that are owned locally and tailored to what one codebase needs, which makes the tool both faster and simpler.

There is an older name for what I want from those chunks. Rico Mariani called it the [pit of success](https://ricomariani.medium.com/pit-of-success-a-2003-ad-lib-ffb05ccdd2c6): a platform built so that people fall into the right practice, with no willpower needed. For human developers that is good design. For agents it matters more, because **an agent that hits a blocker does not stop**. It reverse-engineers the code around it and still produces work that looks valid. A primitive removes the reason to do that: *the right way through is also the shortest one.*

Two releases point the same way. Vercel launched [Board](https://vercel.com/blog/introducing-vercel-board) as an experimental primitive for agents: a message store they use through a CLI, an SDK and a skill. Guillermo Rauch calls it a "headless Slack" for agents, with "no heavyweight or opinionated UI". [UI SDK](https://ui-sdk.dev/docs.md) ships UI behaviors as primitives that an agent assembles into components, and it lets an agent read a running component's state and call its actions. I read both as products turning into primitives: small, refined parts that share one language, so an agent can build the final product from them, then understand and control it through the same API, without the menus, forms, or glue added for a person.

What I would keep shared is smaller than a core: a Glossary. I take the term from [Matt Pocock's skills](https://github.com/mattpocock/skills/pull/1120), where `GLOSSARY.md` is the one file that holds a project's vocabulary, so that every person and agent on it uses the same words in the same sense. Here the Glossary is the language the blocks share, and everything built from it is owned locally.

*Picture: A board with six small blocks seated in it, each in its own recess: parse, routes, tokens, graph, docs and preview. They differ in size and height. One stands half out of its seat, and the empty recess shows under it.*

The blocks can start from a registry, in the manner of shadcn/ui, but once an agent has fitted them to the repository, they belong to it. That means an agent can reshape the pit itself as well. A Glossary is still a document, so it cannot eliminate drift on its own. What it does is **shrink the shared surface area** to one small vocabulary file and a suite of contract tests[^3] that every locally tailored block must still pass.

## What I expect

The programming language will become a matter of mechanics, not preference. When I read a liquid thermometer, I note the line at the fluid's level and rarely care what the fluid is made of, as long as it holds within the range I am measuring. For most product behavior, I care as little about the language underneath a program, and for much of what I build, that is already true.

Once every role can read and edit a blueprint like the payment flow's, the direction of compilation starts to invert. I expect programs to be read and judged in the structure of natural language, open to finer and finer technical detail. **The blueprint becomes the source**, the thing people keep and change, and the code is what an agent builds from it. Picture it as recursive text: a passage that opens into deeper passages as you zoom in. Engineers would inspect behavior instead of code.

*Picture: the payment flow as recursive text. Each phrase opens a deeper passage, written in on demand, and three levels down is the code. Written out:*

A shopper fills a cart, pays for it once, and gets an order. If the card is declined, nothing is charged. Each order keeps a page of its own.

- **fills a cart:** A sheet over the shop page. The total is the items less the discount, and a first order takes 10% off.
  - **total is the items less the discount:** Each line is a price times its quantity. The discount comes off after the sum, and the total never goes below zero.
    - **the total never goes below zero:**

      ```ts
      // Cart: the items less the discount.
      const total = (cart: Cart) =>
        Math.max(
          0,
          sum(cart.lines) - cart.discount
        )
      ```
  - **first order takes 10% off:** The offer is for a shopper with no orders yet. It comes off once, at the total, and shows on the cart’s sheet.
    - **comes off once, at the total:**

      ```ts
      // A first order: 10% off.
      const discount = (cart: Cart) =>
        cart.firstOrder
          ? sum(cart.lines) * 0.1
          : 0
      ```
- **pays for it once:** Full screen, three fields. It charges the card once, even when the shopper presses pay twice, the network times out and tries again, or a step after the charge fails.
  - **charges the card once:** Every charge carries a key made from the cart’s id. The bank keeps the first charge for a key, and answers any repeat with it.
    - **keeps the first charge for a key:**

      ```ts
      // Keyed by the cart: one charge.
      payments.charge(
        card,
        total(cart),
        cart.id
      )
      ```
  - **presses pay twice:** The second press sends the same request, with the same key. The bank sees the key, returns the first charge, and the shopper pays once.
    - **returns the first charge:**

      ```ts
      // Two presses, one key, one charge.
      const pay = Effect.fn("pay")(
        function* (cart: Cart, card: Card) {
          const payments = yield* Payments
          return yield* payments.charge(
            card, total(cart), cart.id
          )
        }
      )
      ```
  - **times out and tries again:** A charge that hears nothing back is tried again after a pause, up to three times. The key is the same, so a retry can’t charge twice.
    - **a retry can’t charge twice:**

      ```ts
      // A retry reuses the key.
      payments.charge(card, amount, cart.id)
        .pipe(
          Effect.timeout("10 seconds"),
          Effect.retry({ times: 3 })
        )
      ```
  - **a step after the charge fails:** The card is charged, but saving the order fails. The charge stays, and saving is tried again until the order exists.
    - **saving is tried again:**

      ```ts
      // Charged, then saved: retry the save.
      Effect.flatMap((charge) =>
        orders.save(cart, charge).pipe(
          Effect.retry({ times: 5 })
        )
      )
      ```
- **gets an order:** Takes the place of checkout. It saves the order and queues a receipt, and counts as a conversion.
  - **saves the order:** The order is written with the charge that paid for it. One charge makes one order, so a repeat finds it already there.
    - **One charge makes one order:**

      ```ts
      // Confirmation: save the order.
      Effect.flatMap((charge) =>
        orders.save(cart, charge)
      ),
      Effect.map((order) =>
        Screen.Confirmation({ order })
      )
      ```
  - **queues a receipt:** The receipt goes out after the screen has changed, so nobody waits on email. It is queued, not sent in line.
    - **It is queued, not sent in line:**

      ```ts
      // Queue the receipt; don’t wait on it.
      Effect.tap((order) =>
        receipts.queue(order)
      )
      ```
- **is declined:** Stays on checkout, with the card marked. The decline says why, and the stock is released.
  - **decline says why:** The bank’s reason is kept as it came. The shopper sees it beside the card field, and can try another card.
    - **sees it beside the card field:**

      ```ts
      // Declined, with the bank’s reason.
      class CardDeclined extends
        Data.TaggedError("CardDeclined")<{
          readonly reason: string
        }> {}
      ```
  - **stock is released:** What was held for the cart goes back on the shelf. The shopper stays on checkout, with the cart as it was.
    - **The shopper stays on checkout:**

      ```ts
      // Failure: release, stay on checkout.
      Effect.catchTag("CardDeclined", (e) =>
        stock.release(cart).pipe(
          Effect.as(Screen.Checkout({
            cart,
            marked: "card",
            reason: e.reason,
          }))
        )
      )
      ```
- **Each order keeps a page:** One page per order, in Account. It reads one order by its id, and shows no offer.
  - **reads one order by its id:** The id comes from the address. The page asks for that one order, and nothing else.
    - **asks for that one order:**

      ```ts
      // Order detail: one order, by its id.
      export const orderDetail = Effect.fn(
        "orderDetail"
      )(function* (id: OrderId) {
        const orders = yield* Orders
        return yield* orders.byId(id)
      })
      ```
  - **shows no offer:** Account is not a place to sell. The page shows the order alone, and nothing on it counts as a step in the funnel.
    - **The page shows the order alone:**

      ```ts
      // No offer here: the order alone.
      Effect.map((order) =>
        Screen.OrderDetail({ order })
      )
      ```

That promise is not new. MDA[^4], UML[^5] and BDD[^6] all tried to make high-level specifications the source, and all ran into the same walls: ambiguity in plain language, broken round-tripping[^7] once someone edited the generated code, and production bugs that the spec never described. A single line like *charges once, safe to retry* still hides idempotency[^8] keys, race conditions, and partial failures. What agents change is the translation cost: they can turn a concise rule into those mechanisms and fold a production fix back into the blueprint without a brittle formal grammar. What they do not erase is drift itself. **It moves**, from docs falling behind code to generated code falling behind intent, and when production disagrees with the blueprint, an engineer still has to drop down to the traces and the code.

One tool has kept the round trip whole. In [XState](https://stately.ai/docs/xstate), a machine's structure is declarative enough that [Stately](https://editor.stately.ai) can render it and write visual edits back to code: the diagram is not generated from the code, **they are two views of the same definition**. Drift moves here too. The structure cannot fall out of sync, so drift collects behind the named guards and actions that still live in code. What it shows is the trade-off: the round trip holds only because the grammar is formal, and a statechart[^9] only describes states and transitions, not the pricing, layout or copy other teams care about. A blueprint does not have to be all prose: where a flow really is states and transitions, that formal skeleton is worth keeping, with agents handling the rest.

Tools may invert the same way. Board and UI SDK are already products turning into primitives, and a tool is only a packaged set of actions, kept so they can be reused and shared. If an agent can assemble those actions whenever it needs them, nobody has to keep the package. The tool becomes something living, assembled just in time[^10] and changed every time it is used.

Another way to see it is as streaming, where what flows is not a film or a song but code, generated and run as it arrives. Versions and packages exist to freeze code so people can agree on what they are running, and just as importantly, to amortize the cost of verification across security fixes, edge cases, and audits. An agent that owns its part, and can change it, test it and run it again, can only do without them **where automated verification is cheap and complete enough to trust every run**. Where that holds, it can keep improving that part with no person in the loop.

For now, the blueprint holds: a person keeps the source, and an agent builds from it. I don't yet know how far that is from a river of code that assembles and runs itself, or what we would have to understand before we could cross it.

[^1]: Inspecting source code without running it, usually by parsing files into syntax trees and following imports and types.
[^2]: When two parts of a system still compile and run, but quietly disagree about what a name, field, or rule actually means.
[^3]: Automated tests that verify the shared inputs, outputs, and invariants a component must honor, regardless of how it is implemented internally.
[^4]: Model-Driven Architecture. An approach that generates executable code from high-level visual or structural models, rather than writing the code by hand.
[^5]: UML. Unified Modeling Language: a standard set of diagrams for modeling a software system's structure and behavior.
[^6]: BDD. Behavior-Driven Development: writing plain-language scenarios (such as Given/When/Then) that serve as both specification and automated tests.
[^7]: Keeping a high-level model and its generated code in sync when edits happen on either side.
[^8]: Ensuring that repeating the same request (after a timeout or double-click) produces the same result instead of charging a customer twice.
[^9]: A visual model of a system's states, the events it responds to, and the transitions between them.
[^10]: Compiled or generated at the moment it is needed, rather than built and packaged ahead of time.
