8BEETY

8BEETY turns any MIDI file into music that sounds like it came out of an NES, a Game Boy, a Super Nintendo, or a Sega Genesis, entirely in the browser, with the file never leaving your machine. It is live, it is free, and the source is public.

One person built it with a coding agent. This guide is the method, not the music.

The big idea

A finished application does not come from one clever prompt.

It comes from three things used together. A written specification with real numbers in it, written before any code. A set of standing rules the agent reads at the start of every session, so you stop retyping your own conventions and start enforcing them. And a loop: build one small piece, test it, hand the result to a fresh context that did not write it, fix what comes back, then move on.

That is the whole thing. Every artifact in this guide is one of those three pieces, lifted out of the real project rather than invented for a tutorial.

Pick a track now

This guide runs on two tracks, and every chapter ends with both spelled out. Choose one before you start reading, because trying to hold both in your head is how a guide turns into homework you never do.

REBUILD. You build 8BEETY, and the repo is your answer key. The chapters tell you what to decide next, and when you get stuck you open the real file and see what the actual answer was. Be honest with yourself about this one: 8BEETY is a four-chip DSP engine with a compiler in front of it, and rebuilding it is a hard first project. Take this track if you have shipped something before and you want to watch the method work on a problem that will not let you fake it.

YOUR OWN. You build your thing, and 8BEETY sits next to it as the worked example. Each chapter hands you the artifact, shows you what 8BEETY put in it, then tells you what yours has to contain. Your project can be a timer, a flashcard app, a tip calculator, an invoice chaser, anything whose first milestone you can describe in one sentence without an "and" in it. This is the right default for most people. It is also the track where the method actually transfers, because you have to make every decision yourself instead of reading someone else's.

What the five artifacts prevent

Each of these has a full page of its own with adaptation notes. Here is the failure each one exists to stop.

• SPEC.md stops the agent from filling your gaps with plausible guesses, which compound quietly until you are debugging a decision nobody ever made.
• CLAUDE.md stops session four from breaking the architectural rule you explained in session one and have not repeated since.
• Milestone plan stops the unreviewable blob: forty new files that demo fine and that you have no way to judge.
• Milestone build prompt stops a task from inheriting three hours of accumulated confusion instead of the one thing you actually want built.
• Fresh-context review prompt stops the context that wrote the code from grading its own homework and finding, every time, that it did well.

How to use them in a coding agent

Put SPEC.md and CLAUDE.md at the root of the repo, next to the package file, where nobody has to go looking. Start a session and make the first instruction "read both of these before you do anything." Then hand it one milestone brief, built from the milestone build prompt. One. Not the plan, not the next two, one. Make it write the failing test before the implementation and make it show you the failure, because a test written after the code is a description of whatever the code happens to do. When the task is finished, close that session and open a fresh one to review it.

That loop has four beats: plan, test-first build, independent review, green gates. The last one means the full test suite and a production build actually run, with the real output in front of you. An agent reporting "all tests pass" is a claim, and you have not seen a result until you have seen the run.

The living project

The repo is not a cleaned-up demo with the scaffolding hidden. SPEC.md is still in it. CLAUDE.md is still in it. docs/superpowers/plans/ holds all twelve implementation plans exactly as they were executed, and the suite runs close to 300 tests.

Keep it open in a tab while you read this. Any time the guide's version of an artifact starts to feel abstract, go and read the real one. The real one was written by somebody in a hurry trying to ship, which is the condition you will be writing yours in.

The chapters are below. Start with the first one.