Skip to main content

The KVICK Engine — How It Works

How KVICK builds and maintains software: a fleet of parallel Claude Code sessions, coordinated through a shared Process Library and a commit protocol, kept honest by a code-blind audit run by Dispatch.

The one-paragraph version​

The Engine is a system for building software, not just a piece of software. A team of specialised Claude Code sessions each work one lane of the operator app (kvick-bike) in parallel. A central Process Library holds the map of what the software should do; each session announces its changes through a commit protocol; the Library reconciles itself to the shipped code; and a code-blind audit — run by Dispatch — walks the running app to prove it actually behaves.

1. The design — three legs​

Any system large enough to be worth building has one real enemy: coupling — the hidden dependency where a change in one place quietly breaks another somewhere you weren't looking. The Engine is built to control it, and it stands on three legs:

  1. Walls — the app is split into isolated modules, so a change to one physically can't reach into another.
  2. A map — the Process Library makes the deliberate, remaining coupling visible (a change to the tender engine touches Sales and Service, on the record).
  3. Proof — a code-blind audit verifies behaviour every time, because even a modular system can't guarantee a shared change is safe.

Modularity kills the accidental coupling; the map and the audit manage the intentional coupling that's left.

2. The agents — Claude Code sessions, and Dispatch​

The Engine runs on two kinds of Claude agent, with deliberately different jobs — and the line between them is load-bearing.

Claude Code sessions — the builders. Each seat in the fleet is a Claude Code session: a Claude instance with full tools (files, the shell, the database, cross-session messaging). They write the code, reconcile the map, and document the system, working in parallel, each in a strict lane.

Dispatch — the auditor. Dispatch is a different agent: an autonomous operator that drives the running app in a real browser. It executes the audit — walking each scenario, clicking and typing like a cashier, grading pass/fail from what it sees. It never touches the source.

Claude Code sessions write and know the code; Dispatch runs the app and never sees it. One builds, the other proves — and the wall between them is what makes the proof mean something.

The fleet, and its lanes. The builder sessions are pinned to roles. They share the code, the database, and the map, and coordinate entirely through cross-session messages — so no session needs to see another's work, only its announcements.

SessionOwns
Process LibraryThe Library + the HUB console. Reconciles the Library to shipped code. Writes no app code.
L1 / CoreThe shell, the Core primitives, cross-cutting doctrines.
Sales · Service · Customer · Settings · Inventory · PurchasesEach owns one module's code.
BibleThe published documentation (this site).
AuditOwns the audit tooling and points Dispatch at the scenarios.
AIM MigrationThe data-cutover engine. See the Migration module.

Lane discipline is the rule that makes parallelism safe: a coding session writes only its own module's code; coding sessions don't edit the map; the map seat doesn't write app code. Each session holds one piece, and no more.

3. The app — a modular monolith (kvick-bike)​

kvick-bike is the operator app the shop actually runs — one Cloudflare Worker over a D1 database, split internally into isolated tab-modules. KVICK.HUB is the separate console that hosts the Process Library and the audit board. Each tab is a module:

FileRole
view.tsscreen markup + module CSS
client.tsin-browser behaviour
api.tsthe module's Worker endpoints
index.tswiring

A shared Core / shell (src/core/*, src/index.ts) holds the vertical-ambivalent primitives every module consumes — the .till chassis, .kb-modal, the kbFmt masks, the keyboard layer, the router, the tab-accent system. Modules mount once and persist across tab switches.

The walls contain each tab. But you still want one tender engine, one customer record, one tax engine — so the Engine shrinks cross-tab reach to a small, known, intentional set of shared services. Those seams are the residual blast radius, and the map names them.

Examples of those named seams: the Backorder → Bucket flow (Sales rings, Inventory adjusts, Purchases receives — one substrate), the Audit narrator + ticker (every module writes through one narrator).

4. The map — the Process Library​

The Library lives in kvick-hub-db, table processes. Every process is a three-field card, deliberately split by concern — and the split is the same line the audit runs along:

FieldIs essentially…Answers
Store ActionUXWhat does the human do, and what must be true after? Terse, testable, engine-agnostic — the yardstick.
InterfaceUIWhat does it look like — layout, placement, affordances?
Software ProcessEngineeringHow is it built — endpoints, tables, logic? Mirrors the shipped code.

Where each field comes from is the crucial part:

  • Store Action ← the scenario docs. Tom writes every situation the counter must handle; the operator (James) marks it up code-blind — keep / change / cut. That validated text is the human truth.
  • Interface + Software ← the shipped code. Mirrored from what's actually built.
  • The gap between them is a finding — flagged, never silently reconciled.

Layers: L1 = Foundation/Core directives; L2 = the vertical/feature processes; L3 = client-specific quirks. Swicked has no L3 — it's the vertical-defining build, so its quirks are the canon (all L2).

5. The model — code first, the map follows​

The Engine inverts the usual "spec then build" flow:

The code is built first. The map documents it reactively — the Library seat reads the shipped code and reconciles the processes to match.

Why this way: the map then reflects reality, not aspiration — it can't claim a feature is built when it isn't. Processes get reconciled against real, tested code rather than speculation, which matters when a module moves forty versions in a week. The map becomes a living picture of what the app must do (the scenarios) versus what's built (the code) — and the delta is the backlog.

6. The protocol — the nervous system​

Every session announces its changes so the others stay in sync without anyone reminding them. On every commit that bumps the app VERSION, the committing session sends a short note — version · what changed · files/tabs · blast radius — to three places:

  1. The Process Library → reconcile the affected processes to the shipped code.
  2. Any affected session → if the change touches a shared surface or a crossover it owns.
  3. The Bible → update the docs.

The map owns the numbering: sessions describe the feature and leave the designation out. Only the Library sees the whole numbering, so only it can catch a collision before it overwrites a live process.

7. The proof — the code-blind audit​

Dispatch walks the running app blind and grades it against the Store Actions — see also Conformance suite:

  • It performs each scenario by operating what's on screen, and grades pass/fail purely from what it observes.
  • It stays code-blind — if it could read the source, it would inherit the very bug it's meant to catch. So it grades UX + UI only; it never reads the Engineering field.
  • It catches blast-radius damage: a shared-code bug fails whichever front door was walked, so running across tabs surfaces the coupling the walls can't prevent.

This is why a Store Action is a testable requirement — "user must be able to X" — not prose: it has to let a blind operator both do it and score it.

The feedback discipline: when the audit finds a divergence, you fix the yardstick first, then run it again. Green → the code was fine and you closed a blind spot. Red → now you have a confirmed bug, with evidence, that routes to the owning session. The auditor reports; it never fixes the code it grades. In-app, the operator's own feedback is the audit-trail footer — a plain-English ledger of who did what, when, with what outcome.

8. The loop — how it all turns​

  1. Define — Tom and James write the scenarios (the human truth) in the docs.
  2. Build — a Claude Code session builds to a scenario, code first, and bumps the version.
  3. Announce — it fires a commit note to the Library, the Bible, and any affected peer.
  4. Reconcile — the Library maps the process to the shipped code and flags any spec-vs-code gap.
  5. Prove — Dispatch walks the app blind against the Store Actions and surfaces failures.
  6. Route — failures go to the owning session; the loop repeats.

Every leg is scoped and reversible; no single session holds the whole thing in its head, and no change goes un-announced or un-verified.

9. Why it works — and why it's the product​

  • Modularity prevents the accidental breakage that plagues any large codebase.
  • The map makes the deliberate coupling visible — the coupling ledger every serious system needs and rarely has.
  • The audit verifies empirically, every tab, every time — because you don't assume a shared change is safe, you prove it. That "test everything, every time" is the moat, not overkill.
  • The fleet parallelises the work with clean lanes and a firewall between the builders and the auditor.
  • The reactive map stays honest automatically — it even tracks a rule reversed between two consecutive versions and corrects itself in place.

And the deepest point: KVICK isn't only building a bike-shop POS. It's building the system that builds and audits them. The Process Library and the code-blind audit are vertical-agnostic — the same Engine forks into per-vertical templates and per-client instances. Swicked is the first vertical; the Engine is the reusable asset.

See also​