From Prototype to Published

1 Division of labour

The three surfaces

Ashaveth was built by three AI surfaces sharing one repository. Each was assigned work its constraints allowed, not work it was nominally capable of. Cowork orchestrated, researched, and verified. Claude Code wrote code, ran tests, committed, and deployed. A Google Antigravity Gemini agent took parallel work that could not collide with the code.

2 How work moves

The dispatch loop

Work moved between agents as written briefs, not conversation. Twenty-six briefs were dispatched in one session, averaging roughly 3.5 kB, the largest 9,338 characters. A brief is not a request — it carries intent, constraints, a write-allowlist, and acceptance criteria that can fail.

The orchestrating agent had no terminal on the target machine, so it drove the other agents through the interface: focus the window, screenshot to confirm state, click the prompt, paste the brief. That sounds primitive. It is also why every instruction had to be complete and self-contained — there was no cheap follow-up. Constraint produced discipline.

Every brief has the same four parts. Intent: what "done" means, in one sentence. Constraints: the rules the result must obey, including what not to touch. Acceptance criteria: a command with a pass condition — if it cannot fail, it is not a criterion. Lane: the paths this agent may write.

3 Concurrency

Lanes, and the diff that must be empty

Two agents editing one repository at once is a merge-conflict problem wearing a speed win's clothes. The answer is a lane: every parallel brief names the exact paths that agent may write, and containment is then proven with a command rather than trusted from a self-report.

A real lane, quoted from a live brief: "Another agent is ACTIVELY EDITING CODE in this repo RIGHT NOW. Do not collide with it. You are READ-ONLY on all code. WRITE ONLY to: docs/**." And for the parallel art run: "This runs in PARALLEL with Claude Code's balance work, so stay strictly in your lane. Adding unused image files is safe and non-colliding." Note the reasoning in that second one — the work was chosen because it could not collide.

Self-reports are not evidence. Containment was verified as code: a git diff scoped to everything outside the allowlist, with the pass condition stated in advance — that diff must be empty.

# 1. what it was allowed to touch
$ git diff HEAD --stat -- docs
  docs/CONTRIBUTING.md | 84 +++++++++
  docs/SECURITY.md     | 61 ++++++
  2 files changed

# 2. everything else. this MUST be empty.
$ git diff HEAD --stat -- . ':(exclude)docs'
  (empty)  ← containment proven

The companion rule is stage explicitly; never git add -A. That rule exists because it was earned: a handoff written by the orchestrator carried a trailing git add -A that would have swept 19 unrelated files into an unrelated commit. The coding agent caught it and asked before running it. Agents checking each other is not redundancy — it is the design.

4 The gate

Two independent passes, then reconcile

The audit gate is the load-bearing part of the loop. Each phase defines intent, constraints, and acceptance criteria; agents execute; then a gate runs that can send the work back. For anything expensive to get wrong, two agents audit the same thing independently and the results are reconciled — because the point of a second pass is the disagreement.

The game-math audit ran this way: two agents, same code, neither seeing the other's findings, both under a hard instruction of audits and testing only — report, do not fix. That constraint existed because it had been violated before, and the correction stuck: a later brief opens "(We got burned before by an 'audit' that turned into edits; not this time.)"

Agreement between passes tells you very little — two agents can share a blind spot. Disagreement is the product. It localizes the error to one of three places: pass A, pass B, or the thing being measured. Every one of those is worth knowing, and you cannot learn any of them from a single pass.

5 The best lesson here

When the harness is the bug

The combat rebalance had a target: every class should beat the final boss without the special weapon, but not comfortably. Two agents simulated it independently. One reported the dragon winnable 60 to 72 percent of the time. The other reported 0 to 10 percent. One of them was badly wrong — and it was the auditor, not the game.

# win% at 5 Full Restores, NO Godsbane, prepared L50 build
boss              Warrior   Rogue    Mage
Golgoth  L20         100%    100%    100%
Malakor  L30         100%    100%    100%
Xel'Nath L40          14%     74%     74%
Ashaveth L50           0%      3%     10%   ← unwinnable?

The tempting move is to raise the alarm: the other agent's rebalance is broken, the boss is unbeatable, escalate. The correct move is to audit your own instrument first. The reasoning, written at the time: "before I alarm anyone, I have to check my model — a wrong harness is worse than none."

It was. The simulation had never modeled the Mage's defensive barrier or any brace-before-a-heavy logic, and it allowed only five potions. Those are not edge cases; they are how the fight is actually played. Modeling them changed everything:

# dragon win% by potion count, defensive barrier now modelled
pots     Warrior   Rogue    Mage
   5         99%     98%    100%
  10        100%    100%    100%

# verdict: my first sim was the bug, not the balance.

Two things make this the strongest lesson on the page. First, the correction was self-initiated — the disagreement triggered self-audit before escalation. Second, the honest caveat that followed was volunteered, not extracted: a hand-rolled model is extremely sensitive to the assumed play policy — that is precisely why the first run looked broken — so the harness can confirm the shape of the difficulty curve but must not be tuned to a specific percent. The real number comes from playtesting.

Reconciled: the coding agent's 60–72% sits inside the independent bracket, between an optimal-play ceiling near 100% and a no-defensive-play floor near 0%. Both passes were right about different players.

6 Honesty

The corrections log

This section exists because the corrections are the curriculum. The orchestrating AI was wrong at least six documented times during this build. None of the errors were exotic — each was confident, plausible, and reasoned. What matters is which mechanism caught each one, because those mechanisms are the transferable part.

7 Infrastructure decides

The filesystem that lies — and commits the lie

The most consequential architectural decision in this build was not made for a good reason. It was forced by a disk. The repository lived on a Windows drive exposed to the orchestrating agent through a mount that silently truncated both reads and writes — sometimes. That single fault decided which agent was allowed to commit.

It surfaced the worst possible way: a commit landed containing 183 lines of a file whose real length was 218, cut off mid-line. Nothing errored. The staging was clean. The commit succeeded. The blob was simply wrong.

And the obvious recovery is a trap. Restoring the file from git would overwrite the good working copy with the bad committed blob — the truncation would win. The verification pattern that actually works: syntax-check the working file, re-commit, then pipe the committed blob back out of git and syntax-check that.

# the working file is fine...
$ node --check scripts/pregen-items.mjs
  ok

# ...but what actually got committed?
$ git show HEAD:scripts/pregen-items.mjs | wc -l
  183   ← the real file is 218 lines
$ git show HEAD:scripts/pregen-items.mjs | node --check
  SyntaxError: Unexpected end of input

# do NOT git checkout — that overwrites the good file with the bad blob.

This is why every commit and every deploy in this project ran on the agent with the native filesystem. Not because it wrote better code — because the other surface could not be trusted to write bytes. The lesson generalizes past this one weird disk: your agents' capabilities are not the only thing that matters. Their substrate is part of the architecture, and it gets a vote.

8 Safety you can prove

Test the guard by defeating it

The prototype's most expensive defect was one string: its API key, sitting in the browser bundle. The fix is architectural — every model call routes through a Cloudflare Worker holding the key as a Worker secret, and the bundle ships a placeholder. But "we moved it" is a claim, and claims decay. So the guard is tested by trying to defeat it.

A postbuild step scans the built bundle for credential patterns and fails the build if one appears. Then the team did the part most teams skip: they poisoned a build on purpose — inlining a fake key and unsetting the proxy URL — and confirmed the scanner exited non-zero.

# deliberately poison: fake key inlined, proxy URL unset
$ npm run build && node scripts/check-secrets.mjs
  scanning dist/ for credential patterns...
  FAIL  credential pattern found in dist/assets/index-*.js
  build aborted — a key must never reach the client
$ echo $?
  1   ← the guard fires. now it is evidence, not a hope.

That experiment exposed a distinction worth internalizing: the dangerous path is conditionally dead, not dead. The build inlines the key only when the proxy URL is unset — so the code is not deleted, it is dormant. One empty environment variable re-enables it. A guard that a configuration mistake can switch off is exactly the guard you must keep testing.

Spend is bounded in layers: an origin allowlist, a model allowlist, a per-session quota, and a per-IP quota. Only one of them protects the wallet — the global ceiling of 5,000 requests per day. Per-user limits shape behaviour; attackers rotate identities. The original per-player quota keyed on a client-supplied header that any user could simply change, which is why the fix pairs a bot-detection challenge with an HMAC-signed session token whose session id is generated on the server. The quota key must not be a value the client gets to choose. And limits are keyed on that signed id rather than on IP, because schools and carriers put thousands of real people behind one address.

9 Generative systems

The unbounded namespace

Late in the build, a player's inventory was full of flat placeholder icons instead of art. The reflex — generate more images — was mathematically doomed. When a monster mints an item name at runtime, the namespace is infinite, and no finite offline batch can ever cover it. That is a resolver problem, not a content problem.

The game generates loot with AI-invented names. Anything not in the static item list becomes a custom item, named on the spot. An endgame bag is therefore mostly items that by construction have no pre-generated art. Shipping more images would have raised the hit rate slightly and fixed nothing.

The fix is a chain: exact art, then a 24-cell fallback matrix covering every item type crossed with every rarity, then a type icon. Every AI drop now resolves to real, rarity-appropriate art, generated once, with zero runtime image calls — preserving the free game's spending guarantee.

The shipping discipline matters as much as the design. The resolver shipped before the images existed — every matrix lookup would 404 and fall through to the icon, which is byte-identical to the previous behaviour. A safe degrade means the deploy cannot regress anyone, and the art can land whenever it lands.

10 Reality

Publishing, and the proof it worked

"It builds" is a small part of "it's live." Shipping this game means a proxy Worker with a hand-set secret, a quota store, a container image, a Cloud Run service, DNS, a TLS certificate, a storefront page, and a smoke test that can actually fail. The build is one step of eight, and not the riskiest.

The deepest trap in the whole project lives here. The AI proxy rejects the temporary cloud URL by design — it is not on the origin allowlist — and the game falls back to pre-written dialogue that is deliberately indistinguishable from live AI. So a developer can test on the temporary URL, see a beautiful, fully playable game, and ship with the signature feature completely dead. The only proof is a specific observable: a 200 from the proxy, in the network tab, on the real origin.

Two more traps from this build, both about things that lie. A .dockerignore once excluded the scripts directory — which would have stripped the secret scanner out of the build environment entirely. A guard that does not exist where the build runs is not a guard. And a PWA icon survived a correct deploy twice: an installed shortcut bakes its icon at install time, and worse, the icon URLs were unversioned while the server sent immutable, max-age=31536000. Same URL, same cache entry, held for a year — even across a reinstall. Cache immutability is a one-year commitment to a mistake. Versioned URLs fixed it.

The server being correct is not the same as the user seeing it.The icon, twice

Reproducible

The loop, end to end

Tool-agnostic, and every step is a scar. Each names the decision, the acceptance test — a command with a pass condition, because if it cannot fail it is not a test — and the failure mode it exists to prevent.

1. Assign by constraint, not capability

   Ask what each surface is structurally unable to get wrong. Let infrastructure decide, and write down why.

   Accept: every task type has a named owner and a stated reason.

   Failure: a truncating mount silently commits a 183-line version of a 218-line file.

2. Write briefs, not chat

   Intent, constraints, acceptance criteria, lane. Complete and self-contained.

   Accept: every brief contains a command with a pass condition.

   Failure: an agent optimizes for the thing you said instead of the thing you meant.

3. Give every parallel agent a lane, and prove it

   Name the writable paths. Never trust the self-report.

   Accept: git diff outside the allowlist returns empty.

   Failure: a trailing git add -A sweeps 19 unrelated files into a commit.

4. Audit twice, independently, then reconcile

   Report only. An audit that edits is not an audit.

   Accept: two passes, neither seeing the other, reconciled in writing.

   Failure: one confident pass and a shared blind spot.

5. Suspect the measurement first

   On disagreement, audit your own instrument before escalating.

   Accept: the harness models the tools a real player actually uses.

   Failure: "the boss is unwinnable" — when your simulation forgot the defensive skills.

6. Log corrections and push them downstream

   When you find your own error, write the correction into the next brief.

   Accept: the corrected model appears in the dispatch, not just the apology.

   Failure: a second agent builds on your bad premise.

7. Verify the artifact, not the source

   Check the committed blob and the deployed origin.

   Accept: git show HEAD:file parses; the live URL returns what you expect.

   Failure: a clean working file and a corrupt commit.

8. Test the guard by defeating it

   Poison a build; watch the scan fail.

   Accept: exit code 1, on purpose, before you trust it.

   Failure: a credential path that is conditionally dead, one variable from live.

9. Cap spend globally

   Layer the limits, but know which one is load-bearing.

   Accept: a hard daily ceiling, and a quota key the client cannot choose.

   Failure: per-user limits and an identity the user can rotate at will.

10. Give unbounded namespaces a fallback

    Generated names cannot be covered by a finite batch.

    Accept: ship the resolver first; every miss degrades to the old behaviour.

    Failure: generating art forever and never catching up.

11. Key caches on stable ids, never display names

    Display names are free to change. Cache keys are forever.

    Accept: rename an entity; confirm no asset is orphaned.

    Failure: a find-and-replace becomes an art-regeneration project. See the receipt below.

12. Re-derive every public number at release

    No figure reaches a marketing asset without a command behind it.

    Accept: each claim carries a command; unverifiable claims are omitted.

    Failure: a page that teaches verification while carrying stale numbers.

The receipt for step 11

This project paid for that rule and then proved it. The game's final boss was renamed during an IP sweep — but its art cache key was pinned to the pre-rebrand string on purpose, with a comment in the code explaining why: renaming the key would orphan the shipped portrait. So the display name moved freely to "Ashaveth, the Red" while the cache key stayed exactly where it was, forever. The same duality runs through the whole bestiary — several monsters carry grimdark display names over legacy art keys, deliberately.

Assign by constraint; brief, don't chat; lane every agent and prove it; audit twice and suspect the instrument; verify the artifact, not the source; and never trust a green signal you have not tried to break.The loop in one sentence

Receipts

Every number, re-derived

This page was built by running the checks it describes. An independent audit re-derived every figure against the repository at a known commit, and two claims did not survive it: the test count and the bundle size. Neither could be executed in the audit environment, so both shipped marked UNVERIFIED rather than guessed — a page about verification that hides its own gaps has taught nothing. Both have since been run on a machine that could execute them, and the numbers are below. The wait was the point: the stale figure was "154 tests," a first re-measurement said "487," and the number that actually reproduces from the commit is 480. Guessing would have been wrong three ways.

Questions

Frequently asked