Projects / Case study

KM Zero

An iPhone running coach. A rules engine builds the plan and adjusts it after every run. Claude picks between the options it allows and explains why, in the runner’s own numbers.

Role
Solo builder, with coding agents
Timeline
October 2026 to now
Built with
SwiftUI, TypeScript, Deno, Supabase
Status
In build, milestone 0 of 9

The problem

Most running plans are fixed. You miss a session or have a bad week, and the plan carries on as if nothing happened. The apps that do adapt usually give you a number with no reason behind it.

An AI coach sounds like the fix, but language models are bad at arithmetic and happy to invent a pace. For training load, a made-up number is how people get hurt.

What I’m building

KM Zero reads the runs people already record in Apple Health. It builds a plan for a race or for general fitness, checks every run against the session it was meant to be, and asks how the run felt. Then it adjusts the next few days if it needs to.

The split of work is the whole design:

After a hard session ran hotTrigger A1
Facts the engine passes in: threshold session, 5 × 1 km. Reps 4 and 5 drifted into Zone 5 and slowed by 4 and 7 s/km. Effort rated 8 of 10. This week: 42 km planned.
  • Shorten Thursday’s easy run from 8 to 6 kmThe rules’ default. Week goes from 42 to 40 km
    Claude’s pick
  • Drop the 6 × 20 s strides from Saturday’s easy runWeek stays at 42 km
    Allowed
  • No changeAlways on the list
    Allowed
Why, as the runner sees itReps 4 and 5 went into Zone 5 and you rated it 8 of 10, so Thursday is 2 km shorter. This week goes from 42 to 40 km.
A worked example from the KM Zero spec. Claude can only return one of the option ids it was given. Every number in its sentence has to appear in the facts, or be a simple difference of two of them.

Keeping the model honest

Every model output is checked before a runner sees it:

A failed output gets one retry with the error attached. If that fails too, the runner gets the engine’s default option with template wording. The plan is always correct, even with the model switched off.

How I’m building it

I wrote the spec before any code: 14 documents, about 2,200 lines, covering the plan engine, the AI contracts, every screen and the test plan. A build plan cuts that into pull-request-sized steps.

Coding agents do the building, one pull request at a time. Each one stops when its PR is green in CI and waits for me to review it. Nothing merges until I say so in the chat.

The engine tests run under both Node and Deno, and a parity check fails any test that passes in only one of them. There are about 200 tests so far.

Where the build is
MilestoneWhat it deliversStatus
M0 FoundationsDomain model, engine skeleton, fixtures, iOS app and CI, accounts5 of 12 PRs merged
M1 Health importApple Health sync, baseline zones and pacesNext
M2 Goal and planRace and fitness plans, the 12 safety rulesPlanned
M3 to M9Today and Plan screens, run analysis, plan updates, progress, releasePlanned
Ten milestones, M0 to M9. Each one ends with a TestFlight build I can run myself.

What’s next