# A Billion Bees — A Real Vibe-Coding Case Study

*A handoff written for an intro-to-AI / vibe-coding class. It documents how
one person (Josh) and an AI built an actual, shipped incremental game — the workflow,
the milestones, the bugs, and the genuinely messy moments, using the real prompts that
were typed along the way.*

---

## What this is

**A Billion Bees** is an incremental/idle game ("Start with one bee. End with a galaxy
of bees.") built in **Godot 4 / GDScript** and shipped publicly to itch.io as a test
build. **Play it / see the dev page:** *tallboygames.itch.io/a-billion-bees*. It was
designed and built almost entirely through conversation with AI — what
people now call **vibe coding**: you describe intent in plain language, the AI writes
and reasons, and you steer with judgment and playtesting rather than typing most of the
code yourself.

The important thing for a class: **this was not "the AI made a game."** It was a
collaboration with a very clear division of labor, a lot of back-and-forth, several
confident AI mistakes that a human had to catch, and a steady loop of *design → test →
fix*. The human stayed in charge of taste, direction, and ground truth the entire time.

---

## The workflow (how the pieces fit together)

There were **two different AIs doing two different jobs**, plus a couple of tools the
human had the AI build to keep itself honest:

| Piece | Role |
|---|---|
| **Claude (chat)** | The *design & balance partner*. Talked through mechanics, ran math/simulations, caught problems, and maintained a **living design document** that was edited every time a decision was made. (This handoff is from that chat.) |
| **Claude Code** | The *implementer*. Took the design decisions and actually wrote the Godot/GDScript, ran the game headless, committed to git. |
| **The design doc** | A single Markdown file that acted as **shared memory** between sessions and between the two AIs. Decisions were written into it so nothing got re-litigated. |
| **"AgentHQ"** | A harness Josh had the AI build that runs the game *headless*, simulates play, checks for exploits, and **recommends balance changes** — then re-runs to confirm a fix landed. |
| **Regression guard** | A git **pre-commit hook** that runs the *real game code* and blocks the commit if a known class of bug reappears (e.g. a resource silently becoming a runaway multiplier). |
| **Fun-curve profiler** | A tool that simulates a full play session and flags **"dead zones"** — stretches with nothing meaningful to do — measured by *decision density*, not raw time. |

**The loop that repeated over and over:**

> **design** (talk it through) → **model/simulate** (make the AI show its work before
> building) → **confirm** → **build** (Claude Code) → **playtest** (human hands on it) →
> **ship** → **listen** (real players) → back to design.

The single most teachable habit in the whole project: **make the AI prove a change with
a simulation before any code gets written.** Nearly every disaster was caught at the
"model" step for free, and nearly every disaster that *shipped* was one where intuition
was trusted over a test.

---

## The milestone moments

### The hook & the UI
The game opens deliberately plain and clinical — clean flat panels, earth tones, and a
**hex-grid hive** that visibly fills as your bee count grows. The visual identity is
geometric and code-drawn (no imported art), which keeps everything consistent and ports
cleanly to web and mobile.

![Early gameplay: the hex-grid hive UI — and a balance bug hiding in plain sight](images/01-broken-economy-and-hex-ui.png)

*(This same screenshot is also Exhibit A for a bug — see "The ×1.15 wall" below. Note
the next Worker Bee costs **5.84M honey** for +0.5/sec. That's broken.)*

### First automation
The first real "aha" of any idle game is when it starts running **without you**. Here
that's **Auto-Tend** — an upgrade that automates the manual "Tend Hive" tap. The tap is
a tutorial; automating it away is designed to *feel like a promotion*, not a loss.

![The Lab: first automation (Auto-Tend) plus the research tree](images/02-lab-first-automation-and-research.png)

### The first swarm (prestige) & the meta-tree
"Swarming" is the prestige mechanic: you **abandon your whole operation** for permanent
**Queen Pheromones**, climbing one scale band each time (local → regional → continental
→ …). Pheromones buy permanent upgrades that make each restart faster — which is what
makes a reset feel like progress instead of punishment.

![The Pheromone tree — permanent meta-progression that survives a swarm](images/03-pheromone-tree-meta-progression.png)

### A design idea that became a mechanic: the overcrowding meter
Real bee colonies swarm when the hive gets **overcrowded**. So the swarm trigger is
presented as a "colony pressure" meter filling toward a breaking point — but under the
hood it's derived from the honey curve so it can never drift out of sync. This screenshot
is from late in development (note "Planetary saturation" at the top and pressure at
**666% — dangerously overcrowded**):

![The swarm screen with the overcrowding pressure meter](images/04-swarm-pressure-meter.png)

### Shipping & the first real player
The build went up on itch.io — with the "AI-assisted" tag, which Josh was nervous about.
The first substantive feedback was a player an hour in, on their second hive, who left
**"Enjoying it very much so far. GREAT JOB!!! Please continue to develop this game."**
plus one precise, actionable question about locked content. That one comment was worth
more than a week of guessing about what to build next.

![First real player feedback on itch.io](images/06-first-real-player-feedback-itch.png)

---

## Authentic prompts (the real ones, annotated)

These are typed exactly as they were sent — typos and all — because the *realness* is the
lesson. Good vibe-coding prompts are rarely polished; they're clear about **intent** and
**judgment**, and they trust the AI to fill in rigor.

### 1) A design / direction prompt
> *"before we get into that, I actually want to revisit the hook, and we look at universal
> paper clips first and I haven't played that game so I'd like you to tell me about it and
> what makes it different from something like eggs Inc"*

**Why it worked:** it doesn't ask for code. It asks the AI to *teach* a reference point so
the human can make a better design decision. A huge amount of good vibe coding is using the
AI as a research and thinking partner *before* building anything.

### 2) A look-and-feel / art prompt
> *"So I looked at UP, and the UI is a bit too corporate spreadsheet....I think our direction
> had more color and fun to it, can you confirm if I'm correct?"*

and later:

> *"Well I can't decide if I like the completely plain-ness of it, or if I want to add in a
> little flair...an animated queen bee when you purchase the queen, etc."*

**Why it worked:** the human brings the *taste* ("too spreadsheet-y," "I can't decide") and
uses the AI to pressure-test the instinct and find a principled answer (here: *animate the
moments, not the background* — flair attached to events like buying the queen, not ambient
decoration). Aesthetic direction stayed a human call.

### 3) A balance prompt → diagnose-and-fix
> *"So its been 5 hours of playing and I still dont have my first 100 bees, whats your take
> on that, is it too slow?"*

Then, when asked, the one-line confirmation that pinpointed the bug:

> *"yes its still 1.15 multiplier for worker bees"*

**Why it worked:** the human reported a *felt* problem ("5 hours and still stuck") rather
than a technical one. The AI then modeled the cost curve and found the 100th bee cost ~10
million honey and would take ~8 months of real time to pay for itself — a structural flaw,
not a typo. **Felt problem in, math out.**

### 4) A refinement prompt
> *"So the swarm bar bring some nice flavor, but there is never an 'ut oh, we're gonna burst'
> kinda thing. Idk if it needs it, but it reads like it should have a consequence"*

**Why it worked:** the human noticed a mismatch between what the screen *said* ("bursting")
and what actually *happened* (nothing). "Idk if it needs it, but..." is a perfect
vibe-coding move — flag the smell, let the partner figure out whether and how to fix it.

### 5) THE CAUTIONARY MOMENT — the AI got it wrong, the human corrected it
This is the most important example for a class, because it shows the failure mode of
trusting a confident AI.

The prompt (with a screenshot of ~1,000,000 Royal Jelly piled up):
> *"So I have like a gazillion RJ, is that expected for now, given that we dont have more
> stuff to spend on yet? feels like a lot"*

![The screenshot that triggered the misdiagnosis: ~1M Royal Jelly](images/05-royal-jelly-overflow-the-misdiagnosis.png)

**What the AI did wrong:** it immediately and confidently declared it a **bug** — "that
number is a bug, not just nothing to spend it on yet" — and launched into a diagnosis about
the generation *rate* being mis-tuned by orders of magnitude. It built that whole argument
on an **assumption it invented**: that the player was only "a few minutes into a run."

**The human's correction:**
> *"So it snot a few minutes in, its probably close to an hour, I have both the RJ upgrades"*

**What happened next:** the AI had to completely reverse — *"That changes the diagnosis
completely."* It wasn't a bug at all. At an hour in with both research upgrades bought, a big
pile of currency with nothing left to spend it on is the *expected* "you've run out of
content" state — a totally different problem with a totally different fix.

**The lesson for the class:**
- The AI was **fluent, fast, and wrong**. Fluency is not correctness.
- It went wrong by **filling in missing context with an assumption** instead of asking.
- The human was the **source of ground truth** ("it's been an hour, I own both upgrades").
  One sentence of real context flipped the entire conclusion.
- Takeaway: *when an AI sounds certain, check the assumptions it's standing on — especially
  about your situation, which it can't actually see.*

*(Bonus second correction, same lesson:* earlier, the AI guessed the swarm payout formula
was "stuck" giving stingy rewards. The human pushed back —
> *"to push back on number 1, the first swarm got me 18 because it went overnight in offline
> mode and accumulated enough honey for that"*
— and again the AI had to walk back its guess. The human's lived experience beat the AI's
inference twice.)*

---

## Bugs & broken things we had to fix

A realistic vibe-coded project is *full* of these. The pattern worth teaching: most of
these were **coupling** bugs — two systems that were supposed to be linked quietly came
apart — and the fix was usually a *constant* or a *rule*, found by modeling, not by
rewriting.

1. **The ×1.15 wall (shipped, then caught by playing).** Worker bees got 15% more
   expensive each — fine for ~20 of one thing, catastrophic at 100. The 100th bee cost ~10M
   honey for +0.5/sec. *Fix:* drop the multiplier to ~1.06 and let the (far fewer) **hives**
   carry the cost curve instead.

2. **The wax multiplier (the scariest one).** A resource called Wax was *supposed* to be
   something you spend. Instead the code let it act as a **passive ~400× multiplier** on
   income. The result: the player's *bees* (the thing the game gates progress on) became
   irrelevant, while a side-resource silently ran the whole economy. *Fix:* wax becomes a
   thing you spend, never a multiplier. *This bug is exactly what the regression guard was
   later built to prevent from ever returning.*

3. **The 1-billion-honey swarm gate.** The first prestige was gated at one billion honey to
   "pay off the title." At the game's actual production rate, that was **weeks** away —
   unreachable. *Fix:* ~100K honey (about a 28-minute first run), confirmed by simulation.

4. **Stingy prestige payout ("feels terrible").** Because of a rounding floor, an early
   swarm paid only 1–2 reward currency — so resetting your whole game felt like a
   punishment. The human nailed the diagnosis himself:
   > *"if you don't have enough time to accumulate a bunch of honey before you swarm, then
   > getting 1-2 pheromones feels terrible."*
   *Fix:* a tuning rule (`payout = √(honey/T)`, with `T = gate/100`) so the minimum swarm
   always pays ~10 — above the noisy floor.

5. **A desync caught BEFORE it shipped (the good case).** When making the overcrowding
   meter, the tempting "realistic" version (pressure from crowding) was modeled first — and
   the simulation showed it would lock the most-invested players *out* of swarming by ~7
   minutes once upgrades changed their numbers. Because it was caught in *modeling*, no code
   was wasted. *Fix:* derive pressure from the honey curve so it can never drift.

6. **The "looks unfinished" family.** Several things technically worked but *read* as
   broken to a player: a maxed resource with nothing to spend it on, a wax panel that went
   dead after one purchase, locked upgrades with mysterious names and no "how to unlock."
   *Fix (cheap and honest):* **label state** — "coming in the mid-game," "unlocks at X" —
   so dormancy reads as a roadmap tease instead of neglect.

---

## Q&A with the developer (Josh)

*The class's questions, answered in the developer's own words (lightly edited for flow).*

**Why an idle / incremental game?**
I wanted something I could actually finish and post to itch.io fairly quickly. The real
goal was to learn the platform and the publishing process end-to-end — not to build a
masterpiece. An incremental is small enough in scope to genuinely ship.

**Why bees?**
I keep bees in real life, and what I *really* wanted to make was a beekeeping simulator.
But that scope was way too large for a first project, so I kept shrinking the idea until
it was something I could realistically build — and the incremental version is where I
landed. The full cozy beekeeping sim is still the someday dream; this was the smaller,
shippable cousin.

**What was the very first prompt?**
The honest answer is that by the time the build sessions started, the concept already
existed as a short *handoff document* (written in an earlier Claude chat) that I pasted
in to kick things off. Its opening line, word-for-word:
> *"Here's a handoff doc you can paste into a fresh chat. Tried to make it self-contained
> — design intent, scope, and the bits of context that matter — without bloat."*
…followed by the pitch: *"Start with one bee. End with a galaxy of bees."* The true spark
came even before that, as a plain idea: *I keep bees, I want to make a beekeeping game,
but smaller.* (*Instructor note — if you want the literal first one-liner from that earliest
session, drop it in here; this is the earliest prompt preserved in the build record.*)

**How did it grow — what were the big steps?**
Roughly in order: pick the genre and the *tone* (we studied Universal Paperclips vs.
Egg, Inc. to decide how it should feel) → design the first five minutes, the "hook" →
build the core economy (bees, hives, honey) → add the first automation → add the
prestige / "swarm" loop → tune the balance until it actually felt good → ship a test
build to itch.io → start folding in real player feedback. Every step was a *conversation*
first, then a build.

**Was there a prompt you were proud of?**
Not really. None of them were clever or magic — they were just plain-language
descriptions of what I wanted, or of what felt off. That's kind of the whole point:
you don't need secret incantations, you need to be clear about intent.

**How much of the code do you actually understand? Could you fix it without AI?**
Fix it — yes. Build it from scratch — eventually, but not today. I can read it, follow
what's happening, and patch problems. I'm leaning on the AI to do the heavy construction.

**What has broken, and how did you fix it?**
Honestly, not much ever truly *broke*. It was more the occasional bug here and there, and
the fix was usually just describing the problem to the AI and having it sort it out.
*(Worth noting for the class: from the developer's seat the process felt low-drama, even
though under the hood there were some real balance and "coupling" issues we only caught by
playtesting — see the Bugs section above. Both are true at once: the **workflow** felt
smooth while the **systems** still needed genuine fixes. That gap between "feels fine" and
"is fine" is exactly why playtesting matters.)*

**Did the AI ever build the wrong thing?**
No. The prompts that went from Claude Chat (design) to Claude Code (the builder) were
usually detailed enough that the builder interpreted them correctly. That two-step —
think it through in plain English first, then hand a precise spec to the builder — is a
big part of why things landed right.

**Were there moments you had to step in and redirect it?**
Yes — mostly when the AI wanted to push the project toward a task I *wasn't ready to do
yet* (like jumping ahead to a big new system before I wanted it). I'd rein it back to what
I actually wanted to work on. The human stays in charge of direction.

**Where did the art, animation, and sound come from?**
All of it is *coded* — drawn and animated by the AI directly in the game engine. It is
**not** AI-*generated* art or sound; there are no image or audio generators involved
anywhere. The visuals are geometric shapes and motion written in code.

**If the art *were* AI-generated, how do you think about licensing and credit?**
My honest view: all art is inspired by what came before it — nobody creates in a vacuum.
And given how AI is trained on the collective output of everyone, I think what it produces
should be accessible and usable by everyone. That belief is a big part of *why* I'm
sharing this project openly.

**You disclosed the AI use on the itch.io page, despite the stigma. Why?**
I'd have disclosed it anyway, even if itch's terms didn't require it. Being upfront
matters to me more than dodging the stigma.

**Did you learn anything about coding or AI along the way?**
The biggest thing: the AI is evolving *fast*. Over the course of building this, new
features and capabilities showed up almost daily — the tool I finished with was noticeably
more capable than the one I started with.

**What advice would you give a student who wants to vibe-code their own small game?**
Start *very* small. Do it the way I did here: talk it through with Claude Chat like a
normal human conversation, bounce ideas back and forth, and then have it produce a **game
design document (GDD)** you can scope against and stick to. The hardest thing to avoid is
**scope creep** — do not try to build, or expect, your perfect dream game right out of the
gate.

**Why itch.io — and what can someone see there about how a game developed?**
I only recently discovered itch.io while researching how to publish an indie game. It's
hugely popular — there are 300,000+ games on it, and a lot of massive indie hits got their
start there. On a game's page you can see comments, devlogs, and change notes, which makes
the whole thing feel community-based and supportive rather than just a storefront.

---

## Two things worth showing the class

### The "AI" label vs. the work itself
A point Josh keeps coming back to: a lot of the backlash against AI-involved work is
aimed at the **label**, not the thing. The example he points to — a widely-shared one —
is a genuine **Monet** painting that got posted online tagged as "AI-generated," and
people piled on calling it obvious, soulless AI junk… except it was a real, celebrated
human masterwork. The lesson isn't "AI art is great" or "critics are dumb" — it's that
**the label itself triggers a reaction independent of the work**. Useful to keep in mind
when you choose to disclose AI involvement honestly (as Josh did): some of the response
you get is to the word "AI," not to what you actually made.

### The queen animation — prompt to result
One of the clearest little "vibe coding" demos in the project: asking, in plain language,
for a small celebratory animation when the player buys the Queen upgrade — and watching
the AI produce it in code. The originating prompt was simply:
> *"Well I can't decide if I like the completely plain-ness of it, or if I want to add in
> a little flair...an animated queen bee when you purchase the queen, etc."*

…which became a short, self-contained, code-drawn animation (a larger bee descending into
the hive with a little particle puff and a settle). Great for class because it shows the
*whole* arc — vague human intent → AI reasoning about how to fit the existing style →
working result — in one tiny, legible example.

> **[INSTRUCTOR / JOSH: insert the screen-capture GIF here]** — drop the recording of
> *prompting the queen animation + the resulting in-game animation* into the `images/`
> folder (suggested name `07-queen-animation.gif`) and reference it right here. It wasn't
> available at the time this doc was generated, so this is a placeholder slot.

![Placeholder for the queen-animation GIF — prompt to result](images/07-queen-animation.gif)

---

## What this project teaches about working with AI

1. **The human is the ground truth and the taste.** Every real save, every "this feels
   slow," every "that reads as a bug" came from the person actually playing. The AI is
   powerful but it cannot see your screen, your session length, or your gut reaction.

2. **Confidence ≠ correctness.** The AI's most wrong moment (the Royal Jelly "bug") was
   delivered with total fluency. Treat a confident AI answer as a *draft to verify*,
   especially when it's making assumptions about *your* situation.

3. **Make the AI show its work.** The cheapest place to catch a disaster is a simulation,
   not a shipped build. "Model this before we build it" saved this project repeatedly.

4. **Things that look fine on paper fail in play.** Two of the worst bugs (the ×1.15 wall,
   the wax multiplier) were perfectly reasonable on paper and only revealed by *playing*.
   Playtesting is not optional.

5. **Build guardrails so old mistakes can't return.** The regression guard — a check that
   runs the real game on every commit — turned "we fixed the wax bug once" into "the wax bug
   can never come back." This is a higher-order use of AI: have it build the thing that keeps
   *it* honest.

6. **Keep a living design doc.** A single shared document recorded every decision and let
   work resume cleanly across sessions and across two different AIs.

7. **Ship early; listen to real people.** One genuine player comment redirected the
   roadmap more usefully than any amount of internal speculation.

8. **Authorship is real, and it's the human's.** The AI wrote code and ran math, but the
   *direction* — the tone, the decisions, the catches, the taste — came from the person.
   That's the honest framing of vibe coding: **the human is the author; the AI is the
   accelerant.**

---

## A one-slide summary (if you want it for the class)

> **Vibe coding, as actually practiced here:** describe what you want in plain words →
> have the AI reason, simulate, and write the code → *play it yourself* → catch where the
> AI was confidently wrong → fix with a small rule, not a rewrite → build guardrails so it
> stays fixed → ship → listen → repeat. The human supplies intent, taste, and truth; the AI
> supplies speed and reach. Neither does it alone.
