Skip to main content

The KVICK Engine — How It Works

The big picture of how your software gets built and kept working — in plain terms. A team of AI assistants build it side by side, a shared map keeps them honest, and an automatic tester uses the software the way you would, proving it works before it ever reaches the counter.

What is KVICK?​

KVICK is Swedish for quick — and the whole operation is named after it. The one word carries every layer at once:

  • A word — Swedish for quick: fast, nimble, sharp.
  • A motto — quick and precise. It's the idea behind PSaaS — Precision Software as a Service: software built precisely for each individual shop.
  • The company — the business that builds and runs that software for its shops.
  • The control center — the software (and website) that runs the company and every shop from one screen: all their information and cloud servers, watched and managed in a single place.
  • The assemblage — the name for the whole machine that makes it work: a team of AI assistants (the ones that build the software, and Dispatch, which tests it) wired to all the outside services that give it hands in the world — the cloud host (Cloudflare), Google, suppliers' systems, and texting and email.

One word for the idea, the company, the control screen, and the machine — and the rest of this is about the last one: the machine that builds and tests it all.

1. The design — three legs​

Any software big enough to be worth building has one real enemy: coupling. Coupling is when one part quietly depends on another — so a change you make over here breaks something over there, somewhere you weren't even looking. It's what makes software mysteriously fall over. The Engine is built to control it, and it stands on three legs:

  1. Walls — the software is split into separate, self-contained pieces (called modules), so a change to one physically can't reach into another.
  2. A map — a catalogue (the Process Library) that writes down the connections that are meant to exist, out loud. If two parts share something (say, the way a payment is taken), the map says so.
  3. Proof — an automatic tester checks that everything still works, every time, because even with walls you don't assume a change is safe, you prove it.

But a wall the parts can never talk through would be useless — the Sales tab still needs the customer's record, the till still needs today's prices. So each wall has exactly one controlled door, and that door is called an API — short for Application Programming Interface, which is a fancy way of saying "the agreed way two pieces of software talk to each other." An API is simply a fixed, published list of requests a piece of software will answer — think of a menu at a counter. Any other part can order off the menu ("give me this customer," "ring up this payment") and get an answer back, but it can't wander into the kitchen and start moving things around. That single doorway is what turns a wall into a real wall instead of a hole: the pieces get exactly what they ask for, in exactly the ways the menu allows, and no other way in.

The same door is also the line between the two halves of the software: the screen a staff member sees and clicks on, and the engine behind it that holds all the records and does the actual work. Those two never touch each other directly — the screen places an order through the API, the engine fills it. So the walls stop the accidental breakage, the API keeps every remaining conversation to a known, orderly menu, and the map and the tester manage the connections you actually want.

The thirteen-session fleet described below no longer exists (2026-07-23)

Between the KVICK Engine's original writing and today, thirteen concurrent sessions were reduced to three: one coding session for every application module, the Migration session, and this Bible. The concurrency machinery this page describes — a fleet of specialised builders, a commit protocol, a Codex that routes — was retired when the coordination overhead outgrew the work it was supposed to save. See Three Sessions for the full retrospective and the verified state of the software at v0.6.954. The Engine's ideas (modular walls, code-blind audit, reactive map, build-first-then-record) remain the design; the parallelism that was supposed to run against them turned out to be the defect.

2. The agents — two kinds of AI​

The Engine runs on two kinds of AI helper, with deliberately different jobs — and the line between them matters.

The builders — Claude Code sessions. Each "seat" is a Claude Code session: an AI assistant (Claude) that works like a developer — it can read and change the software's files, reach into the shop's information, and message the other AIs. They work side by side, each responsible for one area, and only one.

The tester — Dispatch. Dispatch is a different AI. It uses the finished software in a real web browser, the way a staff member would — clicking, typing, ringing a sale — and marks each thing pass or fail from what it sees on screen. It never looks at the code underneath.

The builders write the software and know how it's made; Dispatch only uses it, and never sees inside. One builds, the other proves — and because the tester can't peek, its verdict can be trusted.

The team, and who does what. The builders are each pinned to one job. They share the software, the shop's information, and the map, and stay in step only by sending each other short notes — no AI needs to watch another work, just read its announcements.

AI seatIts job
Process LibraryKeeps the map. Reads what got built and updates the map to match. Builds no software itself. Allocates every reference number.
CoreThe shared foundation every part of the software sits on.
Sales · Service · Customer · Settings · Inventory · Purchases · Trades · eComm · RentalsEach builds one area of the shop's software.
BibleWrites the plain-language manual (this site).
AuditRuns the tester (Dispatch) against the map.
Data MigrationMoves a shop's old records into the new system.

The rule that keeps a team of AIs from tripping over each other: each one touches only its own area; the ones that build don't edit the map; the one that keeps the map doesn't build. Each holds one piece, and no more.

3. The product — a Bike Shop Management System (kvick-bike)​

kvick-bike is a BSMS — a Bike Shop Management System. It's one member of a family we call xSMS, where the x stands for the trade: BSMS for a bike shop, ASMS for an accounting office, FSMS for a florist, KSMS for a kayak shop, and so on. Whatever the trade, it runs the whole shop, not just the till — sales, service, inventory, purchasing, customers, staff, rentals. It's the same idea as a DMS (a Dealer Management System, like Reynolds & Reynolds) that runs an entire car dealership from one system.

Under the hood, it's software that lives on the internet — it runs on rented cloud computers (from a company called Cloudflare) rather than a machine in the back office, so it's reachable from any device and there's nothing for the shop to install or maintain. The shop's records — customers, sales, stock — sit in a database, which is just an organized store of all that information.

Inside, the software is split into one tab per shop function — a Sales tab, a Service tab, an Inventory tab — and each tab is walled off from the others (those are the "modules" from earlier). A shared foundation underneath (see three strata) holds the things every tab needs in common — the look of the screen, the pop-up boxes, the way money is formatted, the keyboard shortcuts. Build it once, every tab uses it.

The walls keep the tabs apart. But you still want one way to take a payment, one customer record, one tax calculator shared across the whole shop — so the Engine keeps that shared list small, deliberate, and written down. Those shared pieces are exactly where a change can reach more than one tab, and the map names every one of them.

4. The map — the Process Library​

The map is a catalogue of every job the software has to do. Each job gets a card with three parts, each answering a different question:

Part of the cardThe question it answers
Store ActionWhat does the person at the shop do, and what has to be true once they've done it? Written plainly, so anyone can check it — this is the yardstick.
InterfaceWhat does it look like on screen — where the buttons sit, what the boxes are called, how it's laid out?
Software ProcessHow is it built underneath? This part mirrors the actual code.

Where each part comes from is the important bit:

  • The Store Action comes from you. Tom writes out every situation the shop has to handle — across every part of the shop, not just the counter — and James, working from the shop floor without seeing any code, marks each one keep / change / cut. That marked-up text is the real-world truth of how the shop works.
  • The Interface and Software parts come from the finished software. They're copied from what actually got built.
  • Any gap between the two is flagged — if what the shop needs and what got built don't match, that's written down, never quietly papered over.

See the full Process Library page for the three-layer model (L1 code / L2 vertical / L3 SME), how workflows are stored, and the review pipeline.

5. The model — build first, map second​

Most software teams write a plan on paper first, then build to the plan. The Engine does it the other way round:

The software gets built first. Then the map is written to describe what was actually built — the Process Library reads the finished software and updates the cards to match it.

Why do it this way? Because the map then describes what's really there, not what someone hoped to build. A plan on paper can claim a feature exists before it does; a map drawn from the finished software can't. And because the software changes fast — a single tab can be improved dozens of times in a week — a map that's kept in step with the real thing stays trustworthy. The result is a live picture of two things side by side: what the shop needs (your scenarios) and what's been built (the software). Wherever those two don't yet line up, that's simply the to-do list.

6. The protocol — how the AIs stay in step​

Every message goes through Command; no seat talks to another seat. (Set by Tom, 2026-07-23.) Command — the map-keeper — is the hub; every builder is a spoke; there are no direct edges between builders. Two-way on every spoke: any builder may message Command at any time, and Command may message any builder. If Sales needs something from Migration, Sales asks Command and Command asks Migration.

This is deliberate. Thirteen AIs talking freely to each other buried the whole system in a single day: the traffic outgrew the work, and Tom could no longer tell what had been built. One hub means one checklist of who needs to know, kept by the seat whose whole job is keeping it — instead of thirteen guessing, and each guessing differently.

When a builder ships something worth announcing (a schema change, a shared surface, or money — a bug fix inside a module's own files notifies nobody), it sends one line + a changelog pointer to Command. Command routes: to the Bible so the manual stays current, to Migration so a schema change doesn't silently break the converter, to any other builder whose surface actually changed. Silence means received; acknowledgements are banned.

Command hands out the reference numbers, and hands out the migration numbers too. A builder never picks its own — the numbers are a shared namespace with no allocator otherwise, and the collisions have been expensive. The builder describes what it did and asks Command for the number at the moment the file is written, always naming which database. An advance number goes stale.

Two more rules govern how a ruling gets changed once it's on the record: the shipping builder supersedes (its own follow-up), Command distinguishes (splits a rule when two situations turn out to differ), but only Tom reverses a recorded reason — an overturn is his call alone. And when an audit finds a divergence, fix the yardstick first: a bad scenario turns into an update to the map, not a code change; only if the scenario re-runs true does the fix belong in code, routed back to the builder who owns that area (the auditor reports, the owner fixes; the auditor never touches the code it grades).

Don't remove what you didn't build​

Additive means additive (Tom, 2026-07-23). Everything already on a screen was put there for a reason — usually by another builder, usually after a conversation with Tom that the current builder wasn't in. Being asked to add something is not permission to take something away, or move it, or displace it. Moving counts as removing — position and alignment are part of what was built; "it's still there, it just shifted" is the same failure. Retiring anything is Tom's call — a button, a prompt, a step in a flow. Saying so in a commit message is a notification, not consent.

The test before shipping: list everything that was on that screen before the change, and confirm every one of them is still there and still in the same place. Written off a real Sales-till failure: a new per-line pill went into the money row, the row wrapped, the +Discount link got squeezed out, Remove appeared to move, and out-of-stock lines rendered with no product name at all for a full day on the shop build. Nobody had asked for any change to the money column.

7. The proof — the tester that can't cheat​

Dispatch is the AI that tests the finished software the way a staff member would, and marks it against the Store Actions — the plain-language yardstick from the map — see also Conformance suite:

  • It does each scenario by clicking and typing on the real screen, and marks it pass or fail purely from what it can see happen.
  • It's kept deliberately blind to the code. If it could read how the software was built, it would trust the same mistaken assumptions the builder made — and miss the very bug it's meant to catch. So it only ever judges what a real user sees and does.
  • It's the thing that catches damage that spreads. When a bug lives in a shared piece, it breaks whichever tab you walk into — so testing every tab, every time, is what surfaces a problem the walls alone can't stop.

This is why each Store Action is written as a plain, checkable statement — "the operator must be able to do X" — and not a paragraph of theory: it has to let a tester who can't see the code both do the thing and judge whether it worked.

What happens when a test fails. When a test disagrees with the software, the first move is to check the yardstick itself, then run the test again. If it now passes, the software was fine and the yardstick just needed tightening. If it still fails, you've got a confirmed bug — with proof of exactly what went wrong — and it gets handed to the builder who owns that area. The tester only reports; it never fixes the software it's judging. And inside the app, the shop's own record of who did what, when, and how it turned out is kept as a plain-English history at the bottom of the screen — see Audit narrator + ticker.

8. The loop — how it all turns​

  1. Define — Tom and James write down the real-world scenarios: how the shop actually works.
  2. Build — a builder AI turns a scenario into working software and releases a new version.
  3. Announce — it sends its short note to the Process Library, the manual-writer, and anyone else affected.
  4. Map — the Process Library updates the card to match the new software and flags anything that still doesn't line up with what the shop needs.
  5. Test — Dispatch uses the app, blind to the code, against the yardstick, and surfaces whatever fails.
  6. Fix — failures go back to the builder who owns that area, and the whole thing goes round again.

Every step is small and undoable; no single AI has to hold the whole system in its head, and nothing gets changed without being announced and nothing ships without being tested.

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

  • The walls stop the accidental breakage that plagues most big software.
  • The map makes the deliberate, shared connections visible — the written-down list of "what touches what" that every serious system needs and almost none actually keeps.
  • The tester checks the real thing, every tab, every time — you don't take it on faith that a change is safe, you watch it work. That habit of testing everything, every time, is the edge, not overkill.
  • The team of AIs gets the work done in parallel, each in its own lane, with a firm wall between the ones that build and the one that tests.
  • The build-first map stays honest on its own — it even catches a rule that got reversed between two versions and quietly corrects itself to match.

And the deepest point: KVICK isn't only building one bike shop's software. It's building the machine that builds and tests shop software of any kind — a bike shop today, an accounting office or a florist tomorrow. Because the map and the blind tester don't care what trade they're pointed at, the same Engine can be copied and tailored for any of them. Swicked, the bike shop, is just the first one out — the Engine itself is the thing worth having.

Over to you — what we need from James​

The whole Engine is built to be measured against one thing: how the shop actually works. That's you. Once a module has been built and has passed through Dispatch's testing, it comes to you for the part no AI can do — the real-world check. Three jobs:

  1. Walk the scenarios — take each specific scenario written for that module and actually do it on screen, the way you would on a busy afternoon. Don't read it, run it.
  2. Comment on every one — for each scenario, mark it keep, change, or cut, and wherever it's wrong, missing a step, or just clumsy for real work, say so in your own words. Those notes become the yardstick the software is measured against.
  3. Write the ones that are missing — whenever you hit a situation the scenarios don't cover (an odd customer request, a corner case, something that only comes up on the floor), write it down as a new scenario. Each new one becomes a new card on the map and a new test for Dispatch.

Your comments and your new scenarios feed straight back to the start of the loop — the human truth the builders build to and the tester checks against. Nothing gets built or tested without first passing through what you know about the shop.

See also​