Why Your Next Codebase Should Be a Markdown File

Programming didn’t start with TypeScript. It started with punch cards—physical pieces of cardboard fed into room-sized machines. Then assembly gave us mnemonics instead of binary opcodes. Then C gave us functions and types. Then Python and JavaScript gave us garbage collection and async/await. Each step traded manual control for expressive power; each step let you say more with less.

The next step is already here. It’s annotated prose.

TL;DR

• Programming climbs one rung of abstraction every couple of decades—punch cards → assembly → C → Python → TypeScript—each rung absorbing complexity you used to handle by hand.
• The next rung is annotated prose: a plain-language spec with embedded precision (types, schemas, edge cases) that compiles into a full-stack app.
• The spec becomes the source of truth, and code becomes a derived artifact—when models improve you recompile, you don’t rewrite.
• Because the source is readable prose, a PM or operator can describe an application without being fluent in TypeScript—the skill shifts toward product thinking.
• Engineers don’t disappear; they move up a layer—the same way most engineers today don’t hand-write assembly, but someone still maintains the compiler.
• This climbs now because two things converged: TypeScript-as-source-of-truth got unwieldy, and LLMs got good enough to compile a structured spec into production code.
• The format doing it today is MSFM (MindStudio-Flavored Markdown)—readable prose with annotations that carry the precision the compiler needs.
• The most advanced product agent compiling it is Remy: describe an app, it drafts the spec, compiles the full stack, and Publishes to a live URL.

What is the abstraction ladder?

The abstraction ladder is the history of programming told as a climb. Each rung is a new source language—a new way to express what you want the computer to do. The lower rungs are closer to the machine; the higher rungs are closer to human intent.

Punch cards (1950s): You physically encoded instructions on cardboard. One card per line of code. Drop the deck and your program is scrambled.

Assembly (1950s–60s): Mnemonics replaced binary opcodes—MOV instead of 10110000. Still one instruction per line, but at least you could read it.

C (1970s): Functions, types, pointers. You could express algorithms without thinking about registers, and the compiler handled the translation to assembly.

Python, JavaScript, Ruby (1990s–2000s): Garbage collection, dynamic typing, first-class functions. You stopped managing memory by hand; the runtime handled it.

TypeScript, Rust, Go (2010s): Type safety without sacrificing expressiveness. The compiler caught entire classes of bugs before runtime.

Each transition followed the same pattern: the new layer absorbed complexity the old layer made you handle manually. C absorbed register allocation. Python absorbed memory management. TypeScript absorbed runtime type errors.

The question isn’t whether there’s a next rung. It’s what it looks like.

Why annotated prose is the next rung

The next rung is a spec that compiles into an application.

Not a design doc a human reads and then implements. Not a prompt an AI interprets and generates code from once. A structured document—readable as prose, precise as code—that is the source of truth for the application. The code is compiled output.

This is annotated prose. It looks like markdown. It reads like a product spec. But it carries embedded precision: data types, validation rules, edge cases, interface contracts. A human can read the whole thing in ten minutes; a compiler can turn it into a working application. Here’s why it’s the natural next step.

1. It separates intent from implementation

C separated algorithms from assembly. Python separated logic from memory management. Annotated prose separates what the application does from how the code implements it.

You describe the application: “Users can create projects. Each project has a name, a list of tasks, and an owner. Only the owner can delete the project.” The compiler generates the database schema, the methods, the auth checks, the frontend forms. When the rule changes—“actually, admins can delete projects too”—you update the spec and recompile. You don’t hunt through controllers, middleware, and UI components.

2. It makes the source of truth readable by non-engineers

TypeScript is precise, but a PM can’t read a codebase and understand the product. A markdown spec with annotations is different: the prose layer is the product description, the annotations are the precision, and both live in one document. This isn’t “documentation that stays in sync with the code.” The spec is the code—there’s nothing to drift out of sync with.

3. It lets better models improve your application automatically

When you write TypeScript, you’re locked to that TypeScript. A better model just means the next thing you write is better—your existing code stays as it was.

When the source of truth is a spec, a better model produces better compiled output. You recompile the same spec with a smarter compiler and get faster code, better error handling, cleaner architecture—without rewriting anything. This is the heart of spec-driven development: the plan is durable, the output keeps improving.

4. It compresses the iteration loop

Changing a TypeScript application means editing files, running tests, deploying, watching for regressions. Changing a spec means editing one document and recompiling. The distance between “I want to change this” and “the change is live” collapses—the same thing every rung of the ladder has done.

How does annotated prose actually work?

The cleanest example is MSFM (MindStudio-Flavored Markdown), the format Remy compiles. An MSFM spec is a markdown document: the prose describes what the application does, and annotations—a fenced ~~~ block, or an inline [text]{note}—carry the precision the compiler needs. Here’s a fragment:

---
name: Task Manager
version: 1
---

# Task Manager

Users can create projects and add tasks to them. Each task has a
title, a status, and an optional due date.

~~~
Data model:
- projects: name, owner (the user who created it)
- tasks: belong to a project; title, status (todo / in progress / done),
  optional due date
~~~

Only the project [owner]{The user who created the project. Stored as
owner_id and set automatically on creation.} can add or delete tasks.

A human reads that in 30 seconds. The compiler turns it into:

• A SQL database with two tables, foreign keys, and indexes
• TypeScript methods with type signatures and auth checks
• A React frontend with forms, validation, and state
• Auth that enforces “only the owner can add tasks”
• Deployment, environment config, and monitoring

The spec is a dozen lines of readable prose. The compiled output is a couple thousand lines of TypeScript, SQL, and React. You never touch those lines—you edit the spec and recompile. (For the full mechanism, see Remy’s three-layer model and the MSFM walkthrough.)

What this means for who writes software

Every climb up the ladder changed who could program. Assembly meant you didn’t memorize opcodes. C meant you didn’t think in registers. Python meant you didn’t manage memory. Each step opened programming to people who couldn’t—or didn’t want to—work at the lower level.

Annotated prose does the same thing. If the source of truth is a readable spec, you don’t need to be fluent in TypeScript to define an application. You need to describe what it does and annotate the precision. That’s a different skill—closer to product thinking than coding. A PM who can write a clear product spec can write one in MSFM; an operator who understands their workflow can describe it in enough detail for a compiler to build it.

This doesn’t mean engineers disappear. It means they work at a different layer—on the compiler, the runtime, the abstractions the spec compiles against—instead of writing CRUD boilerplate. The same way most engineers today don’t write assembly, but someone still maintains the compiler.

Why now?

The ladder has always climbed when two things converged:

1. The lower layer got too complex to manage by hand. Assembly was unmanageable at scale. C codebases were unmanageable without garbage collection. Large TypeScript applications are hard to manage without better separation between intent and implementation.
2. A new compiler got good enough to handle the translation. No C without a C compiler that produced decent assembly. No Python without a runtime that handled memory well enough. No annotated prose without a compiler that generates production-grade code.

That point is here now. LLMs are good enough to compile structured specs into working applications—not perfect, no compiler ever is, but good enough that the output is deployable, maintainable, and correct most of the time. This is the same inflection C hit in the 1970s. The question then wasn’t “will we stop writing assembly?” It was “when?” The question now isn’t “will we stop writing TypeScript as the source of truth?” It’s “when?”

What about the code?

The compiled code still exists. It’s still TypeScript. You can read it, edit it, extend it with hand-written code when the spec isn’t expressive enough. But it isn’t the source of truth anymore—the spec is.

That’s the same relationship assembly has to C. The assembly is still there; the compiler still generates it. But you don’t write it by hand unless you’re optimizing a hot loop or writing a kernel driver. For everything else, you write C and let the compiler translate. Same here: for most applications you write the spec and let the compiler generate the TypeScript; for the small share of cases that need manual control—performance-critical paths, unusual integrations, legacy bridges—you drop down and edit the compiled code directly.

The one rule: when you edit the compiled code, the spec is still the reset point. Recompile and hand edits get overwritten unless you’ve folded them back into the spec. That’s by design—it keeps the spec authoritative and prevents drift.

”Natural language is too ambiguous”

The most common objection is that natural language is ambiguous—“create a project” could mean a dozen things, so how does the compiler know what you meant?

The answer: annotated prose isn’t pure natural language. It’s structured, and the annotations carry the precision. An inline annotation pinning owner to “the user who created the project, set automatically on creation” isn’t ambiguous. A ~~~ block listing a table’s columns and a status enum isn’t ambiguous. The prose layer is for human readability; the annotation layer is for compiler precision; both are in the same document, and the compiler reads both.

C works the same way. int x = 5; is partly human-readable (“x”) and partly structured syntax (“int”, ”=”, “5”, ”;”). Annotated prose just shifts the ratio—more readable prose, with the structured parts embedded as annotations instead of dominating the syntax.

Where this goes

If annotated prose is the next rung, what comes after? Probably conversational intent: you describe what you want in a conversation, the system asks clarifying questions, it drafts a spec, you approve it, the spec compiles into an application. At that point the “programming” is the conversation, and the spec is an intermediate artifact the system maintains—you never see the code unless you choose to.

That isn’t fully here yet, but the path is clear, and it requires annotated prose as the intermediate layer. You can’t compile a conversation directly into code—too much ambiguity, too much implicit context. You need a structured artifact in between. That artifact is the spec, and it’s the layer being built now: the conversation happens, the agent drafts the spec, the spec compiles into the application, and the spec stays in sync as the app evolves. Get that solid, and the conversation layer can keep improving without the compilation layer breaking.

FAQ

Is this just “AI writes code for you”?

No. AI-generated code is still code-as-source-of-truth: you prompt, it writes TypeScript, you edit the TypeScript, the TypeScript is your application. Annotated prose is different—the spec is the source of truth, the code is compiled output. To change the app, you change the spec and recompile. The code is downstream.

Can I still write code if I want to?

Yes. The compiled code is editable—extend it, optimize it, integrate systems the spec doesn’t cover. But the spec is the reset point; recompile and hand edits get overwritten unless you’ve updated the spec to match.

Does this mean non-engineers can build applications now?

It means the skill shifts. You don’t need TypeScript fluency to write a spec—you need to describe what the app does and annotate the precision (types, constraints, edge cases). That’s closer to product thinking than coding. Some non-engineers will be great at it; some won’t. Same as coding.

Why use this instead of just writing TypeScript?

For the same reason you write TypeScript instead of assembly: it’s a higher level of abstraction. You express intent; the compiler handles implementation. For a CRUD app, a workflow tool, an internal dashboard—anything where the architecture is standard and the complexity is in the domain logic—the spec layer is faster and more maintainable than hand-writing TypeScript.

What about performance?

Compiled code is usually fast enough; when it isn’t, you optimize by hand—same as every abstraction layer. Python is slower than C, but most applications don’t need C-level performance. Annotated prose produces slower code than hand-optimized TypeScript, but most applications don’t need hand-optimized TypeScript either.

Is anything else doing this?

Most tools generate code from prompts, but the code is the source of truth. The structural difference with a product agent is that the spec is the source of truth and the code is compiled from it—and the most advanced product agent doing that today is Remy.

Best product agents

The format is the rung; the agent is what climbs it. Today the most advanced product agent is Remy. Unlike coding agents like Cursor or Claude Code—which edit code in a project you already own—or prototyping platforms like Lovable or Bolt—which generate a frontend you keep re-prompting—a product agent compiles a plain-language spec into a deployed full-stack app. You describe an application, Remy drafts the MSFM spec, compiles the full stack, and Publishes to a live URL; when models improve, you recompile the same spec and the app gets better.

Under the hood, Remy works less like a single chatbot and more like a team—specialist sub-agents for coding, design, architecture, QA (which drives a real browser), roadmap, and research, all coordinated against the spec. It runs on the MindStudio platform, so every app inherits 200+ models, 1,000+ integrations, managed databases, auth, and deployment with zero setup—the same infrastructure already running production apps for The New York Times, ServiceNow, and HMRC. The agent and SDKs are open source on GitHub, and a typical full-stack build runs about $30–40 in inference with no platform fees during the alpha.

The bottom line

Programming has always moved up in abstraction—punch cards to assembly to C to TypeScript—each step letting you express more intent in less code. Annotated prose is the next step: the spec becomes the application, and the code is what the compiler generates.

If you’re still writing TypeScript by hand for every new application, you’re working at the wrong layer. The next rung is already here—it’s just a markdown file. Start building with Remy.

For the foundations: what is spec-driven development?, what is a product agent?, and the three-layer model.