Spec first, ship fast: building Pizza with Claude Code

The product

A game platform that happens to start with trivia

The Jackbox model: a host opens a room on the big screen, a QR code and a four-letter room code appear, and everyone joins from their own phone — no app, no accounts, no install. The server is a Node WebSocket relay and the single source of truth; clients render state and emit input, nothing more.

The deliberate twist is in the name of the repo: Pizza is the platform, trivia is a module. The platform core never knows which game it is serving — game rounds cross the wire as opaque payloads owned by the module. And although the product is "AI-hosted," v0.1 contains zero AI on purpose: the roadmap introduces one concern at a time — a deterministic game loop first, Claude calling in via a custom MCP server at v0.3, the app calling out for AI grading at v0.4.

Not a video — a recreation of the real v0.1 screens in the product's own CSS. Every state was verified against a live game played while producing this page: the simulated-player bots Ada and Bex joined room PVPE over real WebSockets, and lost.

The process

Fourteen days, in the order it actually happened

The sequence below is reconstructed from the merge history — and the order is the story. Architecture was decided and reviewed as documents before any code existed; every feature landed as a PR closing a pre-specified issue; reviews produced tracked issues rather than vibes; and shipping produced new decisions, recorded as new ADRs.

Decisions first

An immutable decision ledger

Nine ADRs predate all code; ten predate all feature code. Each is four sections — Status, Context, Decision, Consequences — and none has ever been edited to change a decision. A changed mind gets a new numbered record that names exactly what it extends or reverses, so the ledger reads chronologically: day-one bets, a mid-build course correction, what shipping changed, and a priority shift — with every earlier rationale preserved verbatim, including the reversed ones.

"The immutable ADRs keep their original numbers on purpose. Per the ADR-immutability rule, they are not edited; this ADR is the single source of truth for the remap."

ADR-0013 — changing the plan without rewriting history

The unit of work

Issues you can hand to an agent

Every feature is one GitHub issue with the same five-part shape — and the shape is what makes AI-paired development controllable: Context cites the ADRs, Goal is one sentence, Acceptance criteria are checkable (often literally executable), Out of scope names where each deferral lands, and Notes for Claude speaks directly to the pair programmer.

Architecture

Diagrams that live in the repo

Per ADR-0009, every diagram is Mermaid in markdown — one per file, reviewed in the same PR as the change it depicts. These four are pre-rendered from the repo's own sources.

The invariant

Cheating is a compile error

The headline engineering idea: answer secrecy isn't a code-review guideline, it's structural. The server-only QuestionRecord carries the key; the client-bound QuestionWire declares the key's field as never, so a record is not even assignable to the wire type — and toWire() is the only sanctioned projection between them.

// src/games/trivia/question.ts — the wire type cannot carry the key
export interface QuestionWire {
  readonly id: QuestionId;
  readonly category: string;
  readonly difficulty: Difficulty;
  readonly prompt: string;
  readonly options: readonly string[];
  readonly answerIndex?: never;
}

export function toWire(record: QuestionRecord): QuestionWire {
  const { id, category, difficulty, prompt, options } = record;
  return { id, category, difficulty, prompt, options };
}

And the guard guards itself. The test suite uses @ts-expect-error as a compile-time regression test: if the never protection ever weakens, these directives become unused and npm run typecheck fails.

// src/games/trivia/question.test.ts — a test that runs in the type system
test('a QuestionWire cannot carry the answer key (compile-time)', () => {
  // @ts-expect-error — a full record (with answerIndex) is not assignable to a wire.
  const fromRecord: QuestionWire = record;
  // @ts-expect-error — answerIndex cannot be added to a wire object.
  const smuggled: QuestionWire = { ...toWire(record), answerIndex: 0 };
  assert.ok(fromRecord && smuggled);
});

The same invariant is then enforced at four independent layers — coloured here like the game's own answer identities:

The seam that got repaired in public

The platform/game boundary got its own stress test on day 6. Building the client bus exposed that the wire protocol was trivia-shaped and the "game-agnostic" round engine was reading answerIndex directly — a latent violation of the seam ADR. The response is the pattern worth showcasing: stop, write ADR-0011, and land the repair with the decision in one PR — generic envelopes, module-owned payloads, trivia types relocated out of shared code, and the diff verified by grep: "no game type or wire field survives in src/shared | server | platform | client."

// src/shared/messages.ts — the platform relays payloads it cannot read
export type ServerMessage<Content = unknown, Reveal = unknown> =
  | { readonly type: 'roundStarted'; readonly roundIndex: number;
      readonly content: Content; readonly deadline: number }
  | { readonly type: 'roundResult';  readonly roundIndex: number;
      readonly results: readonly PlayerRoundResult[]; readonly reveal: Reveal }
  // … the reveal exists in exactly one message, by construction

"Left in place, every client (#12–#14) would be built against a trivia-shaped protocol, cementing the leak exactly where it is most expensive to undo. […] The lint rule that forbids the platform from importing src/games/* now has nothing to hide."

ADR-0011 — generic round protocol, written mid-build

The proof that the platform is genuinely generic is also a test: the room lifecycle runs against a StubGameModule with deliberately non-trivia payload types.

Design

The mockups merged three hours before the code

Before either client screen was built, issue #46 produced a UI spec and two standalone HTML mockup galleries — checked into the repo, openable by double-click, covering every state including the edges: 7 host frames and 11 phone frames, join errors and reconnect banners included. The commit log is the receipt: spec and mockups merged at 20:02 on July 15; the host screen landed at 22:56; the player phone at 00:08. Because the mockups used the exact design tokens of the planned app, "the CSS ports directly" — a head start, not throwaway work.

The system is "quiz-show broadcast": a chosen plum-ink ground (not flat black), one magenta accent spent sparingly, and four colour + letter answer identities that match across host and phone — so "I picked the teal one, B" reads across a room. The letter is the primary channel, which makes the coding colourblind-safe; sans-vs-mono is the type system (mono for machine values, sans for prose); dark is primary, light fully designed.

"Semantic green/red appear only as a ring, badge, or check — never as a card fill — so they never collide with an option's identity colour. At reveal, the correct card keeps its own colour and gains a green ring + check; the others dim."

docs/ui-spec.md — the colour rule

Even secrecy shows up in the design layer: the host's mid-round view renders a payload that simply contains no key, so "the host structurally cannot show an answer mid-round." And each mockup ends with a "Decisions I made — and the open questions for you" panel; the spec's decision table records the product owner's ✓ on each call and one explicit ✗ (per-answer vote counts — not in the wire payload, not MVP).

Quality loop

Reviews that produce commits, tests that guard themselves

Quality ran as a loop, not a phase. A multi-agent architecture review on day 5 split its findings by cost: the cheap, high-value fixes shipped same-day as a hardening pass that closed two latent bugs — one of which (an uncaught exception inside a setTimeout tick) would have taken every room in the process down. The bigger findings became tracked issues, landing next as four independently-green commits ordered tests → flake fix → refactor → validation, "so the refactor lands on a hardened, non-flaky suite."

The last ring of the loop is the smoke: npm run smoke boots the built artifact (dist/main.js), waits on /healthz, and has the bot play a full 3-player game with a mid-game reconnect — asserting the round loop and answer secrecy on the thing that actually ships, not just in-process tests.

Ship & operate

A one-person devops loop with no laptop required

The deploy story keeps the architecture honest: ADR-0012 frames the VPS as "a remote always-on laptop" — clients still dial out, state is still files (which finally gain a durable disk). The security insight is where to put the gate: not on loading the host page, but on createRoom over the WebSocket, which a scripted socket could otherwise hit. Basic Auth guards the page; a HOST_SECRET token — injected only into the authenticated page — guards the privileged action; guests need only a room code.

Underneath it all is one zero-config property: the client always dials ws(s):// on the page's own origin — nothing hardcoded — which is why localhost, LAN, Tailscale Funnel, and the Caddy-fronted VPS all run the identical build.

"Sourcing (. env) would parameter-expand the values, and a bcrypt hash is full of $ sequences — under set -u that aborts outright, and otherwise it silently mangles the hash. So read KEY=VALUE literally."

deploy/setup.sh — the kind of comment a pre-merge adversarial review leaves behind; this exact bug was the blocker that "would have failed 100%" of documented deploys, caught before anyone ran it

The playbook

What made the AI pairing work

None of the above required heroics — it required a repeatable working agreement between a developer and an agent. These are the practices this repo actually demonstrates, each with its receipt.

What's next

AI enters one concern at a time

v0.1 proved the loop with zero AI. The reordered roadmap (ADR-0013) now goes breadth-first: v0.2 — polish, reconnection robustness, and a deliberately thin second game module to prove the seam with a real consumer; v0.3 — Claude calls in: a custom MCP server over the question pool (search_questions, add_verified_question, get_game_stats) plus a generate→verify content pipeline; v0.4 — the app calls out: free-text questions graded live by Claude, where answers travel up and the key still never travels down. The parked issues — host accounts, host-paced rounds, the module registry, Docker — are already specified and waiting their turn.