Making English a Programming Language

Product Vault is a public, MIT-licensed harness for building software with coding agents like Claude Code or Codex. It is especially useful for non-technical builders who want to build more complex products without the codebase turning messy.

The short version

Problem

• Coding agents are becoming very good at turning natural language into production-grade code.
• The problem is that they mostly reason from the current codebase and the current chat thread.
• Code records how a product was built. It does not reliably record why it was built, what it is meant to do, or which trade-offs were rejected.
• As the codebase grows, lost intent makes each new change riskier: duplicated paths, weaker modularity, tech-stack drift, and new features that break things that used to work.

Solution

• The missing layer is a product wiki: a natural-language layer above the codebase.
• It stays current with what the product is supposed to do, not just how the code happens to work today.
• The core units are actors, jobs, stories, acceptance criteria, rules, journeys, capabilities, and decisions.
• As the product grows, the wiki also tracks outcomes, non-goals, assumptions, risks, and glossary terms.
• Those units become building blocks. They make the product readable from the top down, so a non-technical person can understand what the product does and why important code decisions exist.
• The important part is that the wiki persists after the chat ends. The same units give the agent something to check before it writes code: what already exists, what to reuse, what must not break, and where the change belongs.

How it works

Shape the request

• You still speak to the coding agent normally: "add this feature", "fix this bug", "change this workflow".
• The harness runs a proposal skill before implementation. It asks questions, finds where the change fits, shows what it touches, and drafts a proposed addition to the product wiki.

Update the product wiki

• Once approved, the product wiki is updated.
• The wiki records what must be true. Those rules and acceptance criteria become executable checks before code is written.

Compile the change

• A compiler skill then turns that wiki change into behaviour, design, implementation steps, code, and checks.
• The sequence matters. It decides the product change first, then the affected journey, rules, capabilities, architecture, checks, and code path. Each decision narrows the next one, so the agent moves from the whole product to the smallest safe edit.

Check and maintain

• Before implementation, design checks ask whether the change can reuse existing parts, fit the architecture, and stay on the chosen stack.
• Specialist subagents are used only when a step benefits from separate review, such as architecture, verification, or consistency.
• Loops keep the wiki, checks, dependencies, architecture, and code aligned over time.

Result

• It works whether you are starting a new product, wrapping an existing codebase, or adding a feature to a mature system.
• It helps non-technical operators, founders, PMs, and domain experts shape software without handing the architecture to a chat thread.
• It helps engineers because requirements, trade-offs, interfaces, expected behaviour, and architecture choices are explicit before implementation starts.
• The result is more consistent software: one product picture, clearer requirements, cleaner boundaries, fewer duplicate paths, less tech-stack drift, and less code that works today but collapses under the next change.

Why I Built This

I am the COO of Ascend, a travel-tech scale-up with 80 people and roughly $25M ARR. Before that I was a founder, product manager, and growth operator. I have always been a builder at heart, but I have never trained as an engineer.

Over the last year, my commit history has started to look like an engineer's. Some of the products I have built with agents are now live in production at Ascend. Others flopped, or worked for a couple of weeks before collapsing like a house of cards.

The good ones had a pattern: clear intent, careful review, and enough structure around the agent that I could judge the work as a non-engineer.

Something has changed in who can build software. Some of us were not trained in traditional programming, but we can reason about product, constraints, tests, and review well enough to direct an agent. However, the failure mode we keep hitting is product mess.

Agents can still produce working code, but every change has to rediscover the architecture. That is how duplicate paths, inconsistent patterns, and fragile branches creep in. The chat box is useful, but it is a weak place to keep all of that together. The repo I am open-sourcing is my attempt to fix that.

The Gap in the Chat Box

Andrej Karpathy put it simply: "The hottest new programming language is English." The problem is that most of us write that language into a chat box, where it gets used once and then disappears into the transcript. The code is left as the durable record, even though code mostly records how the product works, not what the product is meant to be.

Claude Code and Codex can already read a repo, search files, resume transcripts, follow project guidance, and delegate exploration to subagents. That is useful, and it is getting better. The issue is the material they reconstruct from. They mostly reason from the current codebase and the current thread.

Code is a strong record of implementation. It is a weak record of intent.

The missing intent is usually:

• The actors the product serves.
• The jobs those people are trying to get done.
• The rules the product must apply.
• The journeys it supports.
• The behaviour that must always hold.
• The decisions taken and the options rejected.

So the agent rebuilds a guess at your intent from the code each time. The guess is often good, but it is lossy, and it does not accumulate. Better models will help, but they cannot maintain a record of intent that was never written down.

What the Harness Contains

Product Vault sits between the chat box and the codebase. You put in the kind of request you would normally type to a coding agent. Instead of going straight to code, the harness runs a chain of skills.

First, the proposal skill works with you in natural language. It clarifies the request, asks questions when something is missing, finds where the change fits, and drafts the smallest useful addition to the product wiki.

You approve, edit, or reject that proposal. Once approved, the product wiki is updated. Then the compiler skill turns the approved wiki change into design decisions, executable checks, an implementation plan, code, and verification.

That distinction matters. A skill is the playbook that moves the work forward. A subagent is a specialist the playbook can call when separate context helps. Most steps do not need one. Architecture, verification, and consistency review sometimes do.

Take one example: "Customers keep calling on weekends because they cannot change flights while agents are offline." This is what happens to that request.

The core idea is simple. Break the product into the smallest useful natural-language units. Give each unit one job and clear links to the rest of the system. Then turn those units into code in small checked steps.

I call this practical determinism. It does not make the model deterministic. It pins down the behaviour a change must produce, so there is less room for the agent to invent the architecture while it writes the code.

The Product Wiki

The product wiki is the durable record. It is a set of linked natural-language files that describe the product as the smallest useful units. Each unit has one job, a stable ID, and links to the other units it depends on.

A proposal is the gate before code. It asks simple questions: which job does this serve, which journey changes, which capability should be reused, what outcome would prove it mattered, what is deliberately out of scope, what must be true, and what still needs a human decision?

That is the abstraction layer. A non-technical person can read the product from the top down. If they need detail, they can follow the links into requirements, checks, dependencies, and code.

The wiki is harder to ignore than a design doc because it sits on the path to implementation. A new feature, bug, or workflow change does not go straight into code. It first becomes a proposal.

That proposal is a suggested addition to the wiki. You can approve it, edit it, or send it back. Nothing reaches the code until the product change is clear.

The Compiler

The compiler is the workflow that turns an approved wiki change into code. It runs as a disciplined sequence of small decisions. It works on one bounded change, plus the dependencies in its blast radius.

It should not be the same weight for every task. A one-line copy fix can take a light path: make the edit, run the relevant checks, and review the diff. A cross-module product change runs the full path.

The order matters. First, apply the approved wiki change. Then locate the affected product units and code paths. Then decide what to reuse, whether the architecture can absorb the change, what checks prove the behaviour, and what code needs to change. Each step makes one decision explicit before the next one starts.

By the time the model writes code, the hard choices should already be made: what the change must do, what should be reused, how it fits the architecture, and how it will be checked.

This is where the architecture review happens. Before the system writes code for weekend flight changes, it asks: can the current booking architecture support self-serve changes, or would this be another fragile branch inside a module that is already doing too much? If the answer is no, the system raises a refactor proposal before the feature is layered on top.

For a meaningful feature, the compiler runs in six stages.

The model is still probabilistic. The thing pinned down is behaviour, not the exact lines of code. The generated code may differ from one run to the next, but it must satisfy the same acceptance criteria, journeys, and rules. That only means something if the checks run against the code. Otherwise the wiki becomes another stale document with more confidence around it.

What Keeps It Safe

The system is trying to stop the codebase becoming a house of cards. It starts with three plain checks before implementation.

First, reuse. For weekend flight changes, the system should not invent a second flight search or a second fare comparison path. It checks whether the existing capabilities can be reused or extended. It can still propose something new, but it has to explain why.

Second, architecture. The architecture review checks whether the current structure can absorb the change cleanly. If self-serve changes would add a messy set of special cases to the booking module, the system should say so and propose a refactor first. This is the macro check: does the whole product still make sense if we add this?

Third, correctness. The wiki says what must be true: options appear within 60 seconds, fare differences over $500 need confirmation, and payment is not taken until the traveller confirms. Those acceptance criteria become automated checks before the code is written. This is the micro check: did the small change do the exact thing it promised?

For production changes, the compiler also asks the ordinary engineering questions that agents are easy to miss: does this cross a trust boundary, does it change data that needs migration or backward compatibility, and will we know if it fails in production?

The guardrails still matter. Linting, type checks, builds, sandbox rules, hooks, and CI catch the ordinary mistakes models still make. The wiki handles product coherence. The guardrails catch implementation errors and unsafe actions.

The Loops

The first version of a spec is never enough. Products change, dependencies move, tests get stale, and real usage teaches you things the original design missed. The loops keep the wiki and the code from drifting apart after the first implementation.

The practical trick is traceability. A rule, story, or acceptance criterion should have a stable ID. The relevant tests and code paths can point back to it. Then a loop can spot the gaps: wiki claims with no checks, checks with no wiki claim, and code that has drifted outside both.

For the weekend-flight feature, the loops might find four different things.

Some loops only raise proposals because they need judgement. Others can act automatically when the answer is objective and easy to verify. The important point is that the output stays in plain language. You wake up to decisions about the product, not unexplained edits buried in code.

Starting from an Existing Codebase

This also works on existing repos. You can wrap it around a codebase that already has years of decisions inside it.

The first import runs the compiler backwards. It reads the code and drafts a product wiki from what it can infer: the capabilities that already exist, the stories they appear to serve, and the dependencies between them. That first pass is a proposal, not a fact, because the code cannot recover all of the what and almost none of the why.

For a large repo, that import has to be chunked by capability. A huge first wiki would be impossible to review. The useful version is a set of small, low-confidence proposals that a human can accept, correct, or reject.

You review the import the way you review any proposal. You confirm the stories it read correctly, fix the ones it misunderstood, and add the constraints, rejected options, and product rules that were never in the code. From there, every new feature updates the wiki before it touches the implementation.

How It Runs

Underneath, it is a folder of markdown and a small set of agent primitives. AGENTS.md is the portable agent contract. CLAUDE.md should import or mirror that contract for Claude Code. The product wiki is markdown. Skills are the repeatable workflows. Subagents are conditional reviewers. Hooks, scripts, CI, evals, and routines are the guardrails and loops.

The structure follows the LLM wiki idea: keep raw inputs, a maintained wiki, an index, a log, and schema files that tell the agent how to work. The extra layer is the compiler that turns approved product wiki changes into implementation.

The design system belongs in the product wiki too. The principles can be documented in CONSTITUTION.md, but hard rules need enforcement through hooks, permissions, scripts, and CI. The actual design language should live as linked wiki files: principles, tokens, components, accessibility rules, and content patterns. That way UI work is checked against the same product wiki as everything else.

The pages are plain markdown, so any coding agent can read them. The skills are named entry points: propose a change, apply an approved wiki change, compile it, import an existing codebase, reconcile drift, review architecture, and generate checks. Subagents are not one per step. They are called when fresh context helps: architecture review, verification review, and consistency review. Loops run the recurring checks that keep the wiki, design system, tests, architecture, and code aligned.

Coding Without Writing Code

This is coding without writing code. You still do the human parts: decide what should exist, frame the constraints, and review what came back. The translation, typing, wiring, and checking happen a level down.

Good programming languages give you abstraction without losing the path to execution. You write in higher-level building blocks, and the compiler makes the path to the machine repeatable. This harness applies the same idea to product intent. Natural language is the input language. The wiki gives it structure. Executable checks make the behaviour repeatable.

You start in plain language, at the level a product person can read. Follow the links down and the system becomes more precise: jobs, stories, acceptance criteria, checks, dependencies, code. The wiki stays readable. The code is compiled, maintained, and inspectable.

Build Your Own

Product Vault is now live as a public, MIT-licensed GitHub repo. It scaffolds the product wiki, the agent contract, the schemas, the first skills, the hooks, the check manifest, and the maintenance routines. You bring the product.

If you build your own version, tell me where it bends under your work. You can reach me at hi@omarismail.com.