30-minute walkthrough · orient before you write code

§1 Mental model: the four contracts how the build is partitioned

The production build is partitioned across four contracts that lock together. Each contract has a single source of truth and a different drift profile. Get this picture first; every other doc in the bundle slots into it.

Start at the mockup. Walk right. The mockup tells you what the screen is. Tracing the data backward tells you what to build. Most features you finish at Step 3; you only open the ADRs when the spec asks for something non-obvious and you need the rationale.

Design direction is the reverse of reading direction — a new requirement starts as an ADR, drives a schema change, reshapes the API, lands in the visual. You don't need that picture today; the design lead owns it.

The contracts at a glance

Pixel match the visual. Don't paraphrase the schema. Don't add procedures that aren't in the API contract without flagging it. Don't argue an ADR without reading it. Everything else in this bundle exists to make those four things easy.

§2 Bundle tour: where things live three layers, top to bottom

The bundle is a monorepo organised as three layers. Apps sit on top — what users actually run. Packages sit underneath — code shared between the apps. Docs and tooling sit at the bottom — guidance and process. Reading the system top-to-bottom mirrors how an engineer's attention moves on day 1.

Where do I... ?

The diagram shows the shape. The table answers the lookup. Most of day-2 onward, this is what you need:

§3 The docs trees two trees, two questions

docs/ splits into two trees because the work splits into two jobs. docs/spec/ answers WHAT to build — it's the product layer. docs/architecture/ answers HOW it's built — it's the engineering layer. Same bookshelf, two columns.

Spec changes are product changes. A new ADR or a revised binding changes what gets built. Architecture changes are engineering changes. A stack swap or a new flow changes how it gets built. Different review paths, different cadences.

How this maps back to §1

The four contracts from §1 each have a documentation home in this tree. Same shelf, different perspective:

Day-1 reading order

Don't read either tree linearly. Read these six in order, then pull the rest on demand:

§4 The build workflow loop how a feature flows from spec to merge

Every feature follows the same 7-step loop. The names of the files and tools change; the shape doesn't.

§5 The verification mesh four mechanisms that catch drift

Drift between spec / schema / code is the failure mode this bundle exists to prevent. We catch it with a mesh of four independent mechanisms, not a single linear gate. Defence in depth: each mechanism is loose on its own, but together they are hard to slip past.

Mechanism by mechanism

The six slash commands — full reference

Type any of these in Claude Code to load context, run a check, or pull a decision. Each one runs a small shell + file lookup and dumps the result into your conversation. They live in .claude/commands/<name>.md — open one if you want to see exactly what it does.

§6 Phase 0: your day one 9 AM to 5 PM

A concrete sequence for your first working day. Treat the times as a pacing guide, not a strict schedule. If a step takes longer, slide the next one. The goal of day one is orientation — not shipping code.

What success looks like at end of day 1

• You can answer "what are the four contracts and how do they lock together" in two sentences.
• You know which directories you'll open daily (packages/db/src/schema/, packages/api/src/routers/, apps/admin/src/, docs/spec/).
• You have the mockup open in a browser tab and the bundle open in your editor.
• You know what to read next (the rest of CLAUDE.md, more ADRs, the schema design doc).
• You have a list of questions for tomorrow's standup — not a list of code commits.