It all started with a document

This is the second of five posts in the behind-the-scenes series about Olha o Bichim!. In the first, I told where the idea came from. Now, how it became a specification.

The repository's first commit was the project setup, and the second was already a document: docs: add Fase 1 design spec. Before any screen, there was CAPIVARA_2048_DESIGN.md (yes, the game was called Capivara 2048 at first), which today runs to about 1,800 lines. And right at the opening it says who it was written for:

"Specification document for development. Meant to be fed into tools like Claude Code for iterative implementation."

In other words, from day one the main reader of this document was an AI. It contains the vision and the audience, the mechanics, the rule for when a life is consumed (with an action-by-action table), the 14 animals and their colors, the shop, the leaderboard, the palette with hex codes, the duration of each animation in milliseconds, the data model, the phased roadmap and, most importantly, the mandatory test cases and the acceptance criteria for each phase.

At the end, there is even a ready-made prompt for the next phase, ending with a very explicit order: "Don't write code at this stage."

The cycle that repeated about a hundred times

That document was the starting point, but every new feature, every piece of feedback and every bug went through the same cycle:

Idea, feedback or bug, then a brainstorm, which becomes a written specification, which becomes a plan with verifiable steps, which is executed with TDD, reviewed, verified and only then released. There were 95 specs and 101 plans in under six months. A one-day feature, like opening the shop by tapping the coin counter, has its own spec. A big one, like the Wacky Race, a weekly kart event between players, had nine specs in one week, each refining the previous one.

Superpowers, the method in a package

I didn't invent this cycle; I used Superpowers, an open-source set of skills created by Jesse Vincent. A skill is basically a package of Markdown instructions that the agent loads when the task matches its description, and Superpowers brings a whole methodology: brainstorming, plans, TDD, subagent-driven development, code review, systematic debugging and so on.

The detail that makes the difference is that it is quite strict, in a good way. When the session starts, the agent gets a rule saying that if there is even a 1% chance a skill applies, it must use it. And in the game's repository I made that law: no code change without a skill, not even a "small" tweak.

The spec is the source of truth

In practice, this means you first write down what has to happen and why, and the code comes afterwards, judged against the spec.

And the spec always starts from the problem, never from the solution. Some real first lines:

• "The Collection screen is a dead gallery."
• "Users' children played and simply said they 'didn't understand the game'."
• "Apple rejected the iOS submission (Guideline 5.1.1(v))…"
• "Reaching 2048 pays 20 coins, and the amount is the same the first time and the tenth."

There was even a bug whose conclusion was recorded in the design document like this: "the spec below was always right — the bug was in the implementation". When there is a written yardstick, the argument about who is right ends quickly.

First, find out what you want

In Superpowers version 7.0, the brainstorming skill was rewritten from scratch, and its opening is, as I see it, one of the best diagnoses of how an AI works:

"You are very good at building. You build what you believe your human partner wants, and that belief is usually thinner than it feels."

So instead of rushing to code, the agent asks one open question at a time, about a real moment ("when is the moment you miss this?"), without a menu of options to steer the answer. Then it plays its understanding back in parts, marking its own guesses as guesses, and asks what is wrong or missing. It also explicitly asks for the goals, the non-goals and the anti-goals, that is, what would make this a failure even if it technically works.

And it asks "how it will be made": platform, language, libraries. That sounds obvious, but the release notes say why: a session designed an iOS app, never asked about the platform, and built a web app.

At the end of all this there is a gate, the HARD-GATE: nothing is built before the human approves the spec. And a "sounds good" to the idea does not approve a spec that hasn't even been written yet.

Builder check: someone who only has the paper

This is the smartest part of version 7.0. After the spec is written, a new subagent, with no context from the conversation, receives the document and is told to act as the person who will build it, without being able to talk to the author. Its job is to list where it would have to guess, and where a wrong guess would matter.

Each gap falls into one of three buckets: already answered in the conversation (then the answer goes into the spec), minor (the agent decides and marks it as "my call") or the human's (only I know, and the answer changes what gets built). Those of the third kind come in a single round of questions, most important first.

It works because whoever wrote the spec has the whole conversation in their head and "reads" what isn't written. The builder only has the paper, so every question it asks is a real gap that, without this check, the implementer would fill with a guess.

Without gaps, the AI doesn't decide for you

And here is the central point of this post. Faced with a gap, an LLM doesn't stop and ask: it fills it with the most likely answer, and the most likely answer is the internet's average, not what you want. That is how those "AI's own" decisions that contradict what you wanted are born.

Asking why, playing back the understanding with guesses marked, listing what not to do, asking about the platform, marking the agent's decisions as its own, running the text past a builder with no context, and only building after approval: each layer closes one kind of gap. And when, later in execution, the plan and the code diverge, the spec decides, not the agent's guess.

Basically, it is the same thing we do with a new human developer on the team, only written down, versioned and without laziness. In the next post I show the other half: how an approved spec becomes code, and why, in this process, whoever writes is never whoever approves.