Making English a Programming Language

Problem

Coding agents are great at turning natural language into production-grade code, but they mostly reason from the current codebase and the current chat thread. Code records how a product was built, not why it was built or what it is meant to do. As the codebase grows, that lost intent makes each change riskier: duplication creeps in, modularity weakens, stacks drift, and new features start breaking things that used to work.

Solution

The missing layer is a product wiki: a natural-language abstraction layer above the codebase.

It records what the product is supposed to do, why it works that way, and what must stay true as the code changes.

The wiki breaks the product into small units: actors, jobs, stories, acceptance criteria, rules, journeys, capabilities, and decisions.

As the product grows, it can also track 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 the product, follow the reasoning, and see why important code decisions exist.

The important part is that the wiki sits on the path to code. A request, such as a new feature, bug report, or workflow change, becomes a small wiki change first. That wiki change says what should happen, who it affects, what must stay true, and how we will know it works.

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 asks questions before implementation. It finds where the request fits, shows what it touches, and drafts the smallest useful change to the product wiki.

Update the product wiki

You approve or edit the draft. Once it is approved, the product wiki is updated.

The wiki records the required behaviour, rules, and acceptance criteria. Those become checks the agent can run against the code.

Compile the change

A compiler skill turns the approved wiki change into design decisions, checks, implementation steps, code, and verification.

The agent decides what should change before it decides which files to edit.

It starts with the whole product, then narrows to the affected journey, rules, reusable parts, checks, and smallest safe code edit.

Check and maintain

Before code changes, the harness checks whether the product can reuse what already exists, whether the change fits the current architecture, and what must pass afterward.

After code changes, it checks whether the wiki, tests, anchors, and code still agree.

If something objective is missing, it fails a check. If something needs judgement, it asks for a wiki change instead of silently rewriting the product.

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 build software while staying close enough to the code to understand it, review it, and keep control as the product grows.

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 that as our product gets more complex, the codebase also gets more sloppy.

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.

Docs and comments help explain code, but they rarely control how the next change gets made.

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 Wiki sits between the chat box and the codebase. You put in the kind of request you would normally type to a coding agent: a feature, a bug, a workflow change, or a product question.

Instead of going straight to code, the harness first turns that request into a small proposed change to the product wiki. It asks questions when something is missing, finds where the change fits, and writes down what should happen in natural language.

You approve, edit, or reject that wiki change. Once approved, the compiler turns it into design decisions, executable checks, an implementation plan, code, and verification.

One example runs through the rest of the piece: customers keep calling on weekends because they cannot change flights while agents are offline.

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.

The first page is the overview: the whole product in one place before the agent follows links into smaller units.

A request does not go straight into code. It first becomes a proposed wiki change. That draft asks simple questions: which user need does this serve, what should change, what already exists, what must not break, and how will we know it works?

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. Nothing reaches code until the product change is clear.

That proposal is a suggested addition to the wiki. You can approve it, edit it, or send it back.

The Compiler

The compiler is the workflow that turns an approved wiki change into code. It is not one giant prompt. It is a controlled path from product intent to implementation.

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.

For larger changes, the agent decides what should change before it decides which files to edit. It starts with the whole product, then narrows to the affected journey, rules, reusable parts, checks, and smallest safe code edit.

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, permissions, and CI catch the ordinary mistakes models still make. The wiki handles product coherence. The guardrails catch implementation errors and unsafe actions.

The Loops

This is the part that keeps the wiki current without you maintaining it. Products change, dependencies move, tests get stale, and real usage teaches you things the original design missed. The loops do the upkeep after the first implementation: they fix the safe gaps automatically and raise a proposal when something needs your judgement, so the wiki and the code never quietly drift apart.

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

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

Some gaps are objective and can fail a check. Others need judgement and become a proposed wiki change. 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 batch plan: inventory the repo, group related capabilities, import one batch at a time, and leave a resume point so another session can continue without guessing where the last one stopped.

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, skills, scripts, settings, and small reviewer agents. The markdown is the product wiki. AGENTS.md is the portable contract for Codex. CLAUDE.md mirrors it for Claude Code. Skills are the workflows that move a request through the wiki and into code. Scripts, CI, evals, routines, and the lightweight turn-end loop run the checks.

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 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 code can also carry small PW: anchors that point back to wiki IDs, so an agent can grep from product intent to implementation. Subagents are called only when fresh context helps: architecture review, verification review, and consistency review. Loops run the recurring checks that keep the wiki, design system, tests, architecture, anchors, 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 Wiki is now live as an open-source GitHub repo. It scaffolds the product wiki, the agent contract, the schemas, the first skills, the check manifest, the turn-end loop, 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.