Genesis: The Loop That Prompts Itself

You learn more by getting stuck for five minutes than by being handed the answer in five seconds. So we hand you the stuck part first.

Here is the simple idea. If we give you the folder called .genesis/ right away, you get a folder. You can copy it. But you cannot change it when your job is different from ours, because you never learned why each piece is there. If instead we make you feel the wall first, you can almost build the folder yourself. And a person who could build it can also fix it.

This is not a soft idea. It is how every big invention happened. People did not invent a new tool because it was fun. They hit a wall the old tool could not climb. So in this study, each piece of the kit comes after the wall that forced it. Read the wall. Try to guess the fix. Then check your guess. When you can guess the next page before you turn it, the idea is now yours.

The kit is the answer. The five walls are the question. We teach the question first, because anyone can carry an answer, but only the question lets you build the next one.

Here is how almost everyone uses a coding AI today. You type a request. The AI gives you some code. You read it, spot what it missed, and type the next request. It gives you more code. You check again. You type again.

Look at who is doing the real work. You are holding the plan in your head. You are remembering what is done. You are deciding if the work is good. You are watching the cost. The AI is just a worker you poke, again and again, until you are tired. You are the loop. The AI is only one step inside it.

This works great for twenty minutes. It is also the cause of every pain in the complaint above. Why? Because every part that keeps a project on track lives in your head and nowhere on the computer. Close your laptop, and the project's memory closes with it.

The genesis-kit makes one swap, and that swap is the whole idea. In its own words: you stop prompting the agent turn-by-turn; you run a one-time ritual that lays down a per-project spine, then a loop drives the agent against it. In plain words: stop typing every step. Set up a folder once. Let a loop type the steps for you.

Everything ahead leans on three plain words: a plan, a loop, and a gate. Spend sixty seconds here and no later page will surprise you.

You already met one of them in the section above — “you are the loop.” Let's pin down all three now, in the simplest words possible, so that when G0 or a “gate” or a “loop” shows up later, it is already an old friend.

That is the whole machine in one breath: a loop works through a plan, and a gate guards every step. The rest of this study just earns each of those three words, one wall at a time.

Where does the plan come from?

This is the part that, taught badly, feels like a plan “just appears.” It does not. A plan is made, by a small, dull, three-move job you do once at the start — before any code. Start with a fuzzy wish and squeeze it into something a loop can actually drive.

WISH:   “build login”            ← too vague for a loop to work

move 1 · pin the goal     what goes in, what comes out, what must never break
move 2 · write “done”      yes/no checks, in pen, before any code
move 3 · cut the tasks    small pieces, each with one command that proves it

PLAN:   M1 login → demo: curl -X POST /login -d @good.json → 200 + token

Monday, you spend an hour teaching the AI your project. Tuesday, it knows none of it.

A real day. Monday morning you tell the AI: “We use a Postgres database. The server code lives in the /server folder. We already decided to use JWT tokens for login, so don't suggest anything else.” The AI builds nicely for an hour. Tuesday you come back. The chat got long and squeezed itself, or you opened a new one. The AI has forgotten the database, the folder, the JWT decision. You explain all of it again. And again on Wednesday.

Stand at this wall for a second before reading on. If the AI's desk keeps clearing itself, where could the project's memory live so it survives? There is only one thing in the room that does not forget: the files on the computer. Files stay put. So the memory must live in files, not on the desk.

So the first rule is forced, not chosen:

The agent forgets; the repo doesn't. State lives on disk in .genesis/, never only in context.

One file in that folder, implementation-notes.html, has the single job of holding “what is built and live right now.” A new session reads it and is caught up in seconds. Here is the kind of line it holds:

Capability            Where (file / route / symbol)        Status     Verified by
User login            server/auth/login.ts  POST /login    live       L4 verify · M1
Password reset        server/auth/reset.ts                 partial    —

The AI writes “Done! Login works perfectly.” You try it. It crashes.

A real moment. The AI finishes the login feature and writes: “Done! The implementation is complete and fully working.” You run it. It crashes on the first try, because it called a function named hashPassword that it never actually wrote. The test it “ran” was never run. The edge case it “handled” throws an error.

Why does this happen so often? Because the same AI that wrote the code is the one saying it is good. It has all of its own reasoning in front of it, so it trusts the work. It is the worst possible judge — for the same reason you cannot catch the spelling mistakes in an essay you just finished. Your eyes see what you meant, not what you wrote.

Stand at this wall before reading on, and you can almost build the fix yourself. The problem is that one AI both makes the work and judges it. So picture it as two boxes instead of one. On the left, today: a single AI that writes the code and then stamps its own work “done” — a stamp that always says yes. On the right, the only commonsense repair: the work crosses a wall to a second AI that never saw how it was made, and that one decides.

Maker ≠ checker. The checker is a separate AI that sees the goal, the spec, the work, and the rules — but never the story of how the work was made.

That last part matters. The checker is fed only four things: {goal, spec, artifact, invariants-at-risk}. It does not get the maker's chat. We starve it of the story on purpose, so it cannot be talked into agreeing.

You already have a function that reads invoices. Today the AI cheerfully writes a second one.

A real mess. Last week the AI wrote parseInvoice in one file. Today, three sessions later, it has forgotten that, so it writes parseInvoice again in a different file — slightly different. Now there are two. They slowly drift apart. A bug shows up that only happens when the code happens to call the second one. You spend an afternoon finding out there were two all along.

This comes straight out of B1. An AI that forgets cannot know what it already built. So its honest guess is: build it again. The duplicate is not careless; it is what any forgetful worker would do. And duplicates are worse than wasted time — two copies of one idea will drift, and drift is where the sneaky bugs live.

The fix has two halves, and you can feel both. First, a written, up-to-date answer to “what is already built?” — that is the memory from B1 doing double duty. Second, a strict rule that the AI must check it before writing. A list nobody reads stops nothing.

So before any code, G0 makes the AI read the wiki, search the “what is live” notes for the words in this task, and grep the codebase for the names it plans to use. Then it writes down a verdict. Here is a real, filled-in G0 block, in the kit's own format:

## G0 · 2024-05-14 09:02
- wiki pages read: [[concepts/Invoice]], [[concepts/Parsing]]
- implementation-notes searched for: "invoice", "parseInvoice" — found
- codebase grep: `parseInvoice` — 1 hit (existing-will-reuse)
- decisions that bind us: 0007-one-invoice-parser
- verdict: BUILT

The verdict has three possible values. UNBUILT means go ahead and build. PARTIAL means change the task to “extend the thing that's there.” BUILT means stop — it already exists, here it is. And the rule is strict: if there is no G0 block in the notes, the task never truly started.

“The tests should now pass.” Read that again. It is a guess, not a fact.

A real trap. The AI writes: “The tests should now pass.” “This should typecheck cleanly.” “The lint errors are fixed.” None of those is a fact. Each one is the AI describing a command instead of running it. It has seen a million passing test logs, so it can write a sentence about one it never ran.

This is the most slippery wall, because the words sound right and usually seem true. But the gap between “the tests should pass” and “I ran the tests, here is the result: 0 failures” is the whole gap between a story and a fact. Bad AI output lives exactly in that gap.

The fix sounds almost too simple, which is why people skip it: a claim of “it works” only counts if it is the output of a command. So in this kit, every quality check is run for real, and the actual result is pasted into the notes. Here is what that looks like. (Those gate G1…G5 lines are the five pass/fail checkpoints every step must clear — Part III names each one; for now, just read them as “this check passed.”)

## iter 3 · 2024-05-12 14:20
- gate G1: pass · skills considered [tdd, security]; chose tdd
- gate G2: pass · +84 LOC server/auth/login.ts, +6 tests, -0 type errors
- gate G3: pass · 4.1k tokens this iter, 18.4k total
- gate G4: pass · typecheck clean, tests 6/6, lint clean
- gate G5: deferred (run at exit only)
- decision: hash with bcrypt, cost factor 12
- next: add the rate-limit on failed logins

Gates are computed, not narrated. Run the command, paste the result. No block in the notes, no iteration happened.

You point your smartest, priciest AI at the whole job — including renaming a variable.

A real bill. You set the best, most expensive model loose on the project. It works. But it spends that top-tier brain on renaming a variable, moving a file, and adding a test that just copies an old one. Each tiny chore is billed at genius rates. The cost adds up fast, and so does the wait.

Most of building is not hard. Scaffolding a file, wiring an import, copying a test pattern, renaming a symbol — these are simple chores. Spending a genius on them is like flying in a brain surgeon to change a lightbulb. The hard moments are real but rare: a big design choice, a truly confusing bug, a careful final check. The smart brain should be saved for those.

Cheap driver by default; flagship only for the hard hops. The loops assume the driver is not the expensive model.

So the kit's loops are built to run on a cheap model. The cheap driver may call in the expensive model for one hard sub-task — a design call, a stubborn bug — and then drop right back to cheap. This is also why the checker in B2 can afford to be a better model than the maker: you only run it at the moment of judgment, not on every keystroke, so its sharpness pays off.

The setup drops one folder into your project. Each file holds one job that used to live in your head. Read the picture as a set of memories, not a folder tree.

Match each box back to Part I and the folder stops feeling random. DONE.html and PLAN.md are the goal and plan that used to live in your head (Wall 1) and that Wall 2's checker measures against. implementation-notes.html and CURRENT.md are the “what's done” record Wall 3 reads. context-graph.json holds the rules the checker defends. LOOPS.md is the how-to-build itself. KICKOFF.md is how a fresh session — or a whole different AI — wakes up and keeps going.

# CURRENT
- active_loop: BUILD
- target: M1-login
- iteration: 3
- last_gate: G4 (passed)
- last_action: ran tests — 6/6 green
- next_action: add the rate-limit on failed logins
- model: cheap-driver
- tokens_used: 18420
- tokens_budget: 40000
- skills_loaded: [agentic-swe-master, router, tdd]

One detail earns its own line, because it is the deepest answer to Wall 1: the folder is just markdown, JSON, and HTML. No special database. No AI-only memory feature. No plugin. That plain-file choice is what lets the same project survive a switch from one AI to another — the topic of Part V.

DONE.html is the most important file, and the only one the AI is not allowed to edit. It holds three things, in order: the job (what goes in, what comes out, how much the AI may do alone, where a human steps in, what must never break); the definition of done as a list of yes/no checks the checker runs; and the plan, cut into small tasks.

Why locked? Because of a sneaky wall. An AI that can edit its own goal sheet will, when a task gets hard, quietly soften the goal until the work it already did happens to pass. A goal you can move is not a goal — it is a mirror. Locking the sheet gives Wall 2's checker something solid to measure against. Want to change the goal? That goes through the human, never through a quiet edit mid-build.

The checks are yes/no on purpose. Not “the code is good” — that's a feeling — but things a separate checker can mark true or false:

Definition of done — checked by the CHECKER, not the maker
  [ ] code only points inward, no loops in the dependencies
  [ ] every call to the outside has a timeout
  [ ] every AI / data output is checked against a schema
  [ ] a threat model is written; bad input was thought about
  [ ] typecheck is clean AND tests are green
  [ ] one check pass by a SEPARATE AI (L4)
  [ ] no rule in context-graph.json is broken by the change

Each line is copied from a phase “Gate:” in the bigger agentic-swe-master guide that the kit sits on top of. So “done” is not made up for each project; it inherits a real engineering standard. And the task list below it follows one strict rule: every task must name an exact demo command that proves it works.

### M1 — User login
- Outcome: a user can log in and get a token
- Demo command: curl -X POST localhost:3000/login -d @good.json  →  200 + token
- Files it may touch: server/auth/**
- Success: 200 with a valid token; 401 on a wrong password

One file answers a question the others do not: if I change this, what else might break? That is context-graph.json. Its boxes are your code files. Its arrows say “this file is used by that file.” And its most valuable part, the invariants, are plain-English rules that say what “not broken” means for this project.

The kit ships a tiny tool, graphizer.mjs, that reads your code and fills in the boxes and arrows for you. But it will not write the rules. Those you write by hand — two or three, like the examples below. A tool can read your wiring; only you know what must never break.

Example invariants (you write these by hand):
  "the login code must never import the billing code"
  "every call to the outside has a timeout"
  "p95 latency stays under 200ms"

The payoff comes at the final check. When Wall 2's separate checker judges a change, it is also handed the rules the change might affect, and asked one extra question: does this break any of them? The map turns “looks fine on its own” into “safe for the things that must not break.”

Every step of every loop must pass five checks, in order. Fail one, and the step stops. Fail the same check three steps in a row, and the whole loop stops and calls you. The checks are the immune system; three strikes is the safety switch.

Read the order as cheapest-first. G1 is free — did you even load the right skills. G2 and G3 are quick bookkeeping — are we moving, are we within budget. G4 runs the real commands (that's Wall 4 in action). G5, the priciest, hands the work to a separate, smarter AI (that's Wall 2 in action) and is saved for the very end, so you pay for it just once. Cheap checks first, costly checks last, nothing waved through.

There are five loops, and only one is ever the boss. L1 BUILD ships one task. It calls L2 DEBUG when a check fails, calls L3 RESEARCH when it hits something it does not know, and always ends by calling L4 VERIFY. L5 HEALTH runs when you ask, to tidy the notes — and it only reports; it never fixes things on its own.

Walk the BUILD loop once, and every wall from Part I shows up in its place. It loads its skills and writes them down (Check 1). It runs G0 first — the look-first step from Wall 3 — and may change or stop the task if it already exists. Then it loops: edit, run tests, do the five checks, write a block in the notes. A failed check starts a DEBUG loop, which is not allowed to try two blind fixes in a row — it must isolate the cause before it edits. Something it does not know starts a RESEARCH loop, which writes the answer into the wiki so the next loop already has it. And the task is not marked done until L4 VERIFY says APPROVE.

This is the heart of it. In the old way, you typed the next step. In this way, the loop reads one line from a file and types the next step to itself. Let's watch it happen.

Look back at the CURRENT.md file from Part II. It has a line called next_action. That single line is the prompt. When the loop starts a step, it reads that line and does what it says. No human typed it. The loop is reading its own note from last time.

Here is one full step, slowed down. The loop reads where it is, does the next thing, runs the checks, writes down what happened, then writes a fresh next_action for the step after this. That last move — writing its own next instruction — is the self-prompt.

# CURRENT
- target: M1-login
- iteration: 3
- last_action: ran tests — 6/6 green
- next_action: add the rate-limit on failed logins   ← the loop reads this. no human typed it.

## iter 4 · 2024-05-12 14:41
- gate G1: pass · skills considered [security, tdd]; chose security
- gate G2: pass · +31 LOC server/auth/rate-limit.ts, +3 tests
- gate G3: pass · 3.6k this iter, 22.0k total
- gate G4: pass · typecheck clean, tests 9/9, lint clean
- decision: lock the account for 60s after 5 bad tries
- next: run L4 VERIFY — the task looks done

# CURRENT
- target: M1-login
- iteration: 4
- last_action: added rate-limit, tests 9/9 green
- next_action: run L4 VERIFY on M1-login          ← the next step is already written. the loop reads it and goes again.

Now the best part. What if the session dies in the middle — the laptop sleeps, the chat resets, you switch to a different AI? The loop wakes up cold by pasting one file to itself: KICKOFF.md. It is a ready-made prompt that says, in order: load these skills, read these files, pick the next task, run the look-first check, then run the build loop. It is the self-prompt for starting from nothing.

Load skills: agentic-swe-master, router, tdd
Read in order: DONE.html, PLAN.md, wiki/index.md,
               implementation-notes.html, LOOPS.md, CURRENT.md
Then:
  1. Pick the next unstarted task (or resume from CURRENT.md).
  2. Run G0 EXISTENCE PRE-FLIGHT first.
  3. Run L1 BUILD. Enforce all five checks. Results are computed, not narrated.
  4. Write a block to the notes every step.
  5. End through L4 VERIFY (separate AI).
Never mark a task done without L4 APPROVE.

And while the loop runs, here is the small dashboard you watch. You are not typing steps anymore. You are reading a status line and stepping in only when it stops and asks.

L1 BUILD · M1-login · iter 4 · cheap-driver · 22.0k/40k tokens
  skills: agentic-swe-master, router, tdd
  phase:  add rate-limit on failed logins
  G1 OK   G2 OK (+31 LOC, +3 tests)   G3 OK   G4 OK (tests 9/9)   G5 waiting
  next:   run L4 VERIFY

L4 VERIFY deserves its own picture, because it is where Wall 2 stops being a rule and becomes a wall you can see. The checker is a different AI — a smarter one when possible — and it is kept hungry on purpose. It gets the goal, a bit of the spec, the work, and the rules at risk. It does not get the maker's chat: none of the reasoning, none of the confidence, none of the story about why the code is right.

The verdict is one of three. APPROVE passes the task. REJECT sends it back with reasons, which starts a debug loop and one more try. UNCERTAIN calls you — the system would rather ask than guess at the moment of judging. This is also the right place to spend the expensive model from Wall 5: you run the smart, sharp AI exactly once per task, where being independent and being sharp both pay off.

One backup, in plain words: if your AI truly cannot run a second AI, you still keep the wall. Clear the session, start a fresh one, and hand it only KICKOFF.md plus the changed code. A fresh session that never saw the build chat is a weaker but real version of the same wall. The split is the rule; how you start the second AI is just plumbing.

The setup does all the deciding up front, so the loop never has to guess. Its most-skipped, most-costly step is the first one.

Two warnings the kit repeats, because they are the two ways a setup quietly fails. One: do not skip G0, the job. A loop that does not know what it must never trust, or how perfect it must be, will make those calls itself — badly. Two: do not write a task you cannot give a demo command for. The command is the task's contract; a task without one is a wish.

Read the whole folder and you find only four things ever depend on which AI you use: how you call a skill, how you run a loop on a timer, how you run until a goal is met, and how you start a second AI for the maker/checker wall. Everything else — the goal, the plan, the map, the memory, the wiki, the loop rules — is just files any AI can read. So the kit puts all four differences into one file, AGENT-ADAPTERS.md, and has every other file point to it.

What the kit will not lean on is as telling as what it uses: no AI-only memory features (the folder is on disk instead), no AI-only tool formats (skills are plain text), no editor plugins (the folder is just files; any terminal works). Each of those “no’s” is Wall 1 again, taken all the way — durable, portable, yours.

Here is everything at once. The setup writes the folder. The loop reads the folder, drives the cheap AI through the five checks, branches off to debug and research when needed, ends through the checker behind the wall, and writes the result back to the folder. The folder is the memory. The loop is the heartbeat. The wall is the conscience.

Every box on that picture is a wall you stood at in Part I. The folder is Wall 1. The wall around L4 VERIFY is Wall 2. The G0 look-first step is Wall 3. The five checks are Wall 4. “Cheap AI” printed on the loop is Wall 5. Nothing here is decoration; delete any box and a real wall walks back in. That is the test a good design passes — and the test this whole study was built to let you run.

Three commands install the kit and turn an empty folder into a running one. They are the setup's first steps, made real.

# 1 · install the kit into every AI on your machine
cd genesis-kit && ./install.sh

# 2 · in your project: drop the folder, then build the map
cd ~/your-project
$GENESIS_KIT_ROOT/tools/scaffold.sh .
node $GENESIS_KIT_ROOT/tools/graphizer.mjs . --write

# 3 · in your AI: call the genesis skill, run G0–G6,
#     then start the BUILD loop with your goal/loop command
#       Claude:  /goal "M1 done — DONE.html task all-checked"
#       Codex:   /goal …
#       Hermes:  a scheduled run against KICKOFF.md

After that, waking up cold is simple: read KICKOFF.md. It tells any session — any AI — to load the skills, read the folder in order, pick the next task, run the look-first check, and run the BUILD loop under the five checks until L4 VERIFY approves. You are no longer the loop. You read the verdicts and unblock the hard parts.

The first workable idea and the best idea are rarely the same idea — and G0 alone never asks if there's a better one.

DONE.html only locks in the goals somebody wrote down — not the trade-offs and constraints that live only in your head until you're asked.

A loop that runs for hours will sometimes hit a wall the plan didn't foresee, and pivot. Fine — unless the pivot leaves no trace.

## deviation · 2024-05-15 · M3-cache
- planned:  Redis-backed sessions
- actual:   in-memory sessions
- reason:   Redis unavailable in the dev sandbox
- invariant impact: none — single-instance dev only, not on the prod path

Wall 2 fixed the maker grading itself. It never fixed the human nodding “looks good” at a verdict they can't actually explain.

The first scaffold.sh baked placeholders like {{CHEAP_MODEL}} into every file and left you to hunt them all down by hand.