Work / Our products · 2026

RefClock

A match timer for sports referees on Apple Watch, Wear OS, iPhone and Android

Platforms
Apple Watch, Wear OS, iOS, Android
Built with
Kotlin Multiplatform, SwiftUI, Jetpack Compose (Wear OS), React Native / Expo SDK 55, Style Dictionary tokens
Status
Pre-release
RefClock
Two Apple Watch active-timer screens: a cyan 2:14 warmup countdown and an amber 0:09 timeout warning with team scores

RefClock is a cross-platform officiating instrument for sports referees. It runs on the wrist (Apple Watch, Wear OS) and on paired phones, which mirror the watch as a larger scoreboard. One Kotlin Multiplatform rules engine powers every client, one design-token source drives every UI, and one rules-data format covers every sport.

The problem

Referees time matches with stopwatches, paper cue cards, vendor scoreboard consoles and a few niche apps. The most loved volleyball tool is volleyball-only, Apple Watch-only and maintained by one developer, and it keeps running in the background only if the referee remembers a system setting. Officials in basketball, soccer, hockey and pickleball improvise with general-purpose timers.

The PRD’s users are certified referees, volunteer youth officials, and table workers who follow the match on a phone. The referee reads the watch at arm’s length, in bad light, through sweat or gloves. The cue has to fire on time, unattended, for a two-to-three-hour match.

What we built

A referee picks a sport and a ruleset on the watch and starts the match. The watch runs every phase, from warmup and sets to timeouts and intervals, and fires whistle, horn and beep cues with haptics. It buzzes the last ten seconds of a timed phase, tosses the coin, counts substitutions, and shows a rules reference built from the ruleset itself. A paired phone mirrors the watch as a larger scoreboard. An unpaired phone can run the match on its own. Complications, the Live Activity and the Wear OS tile keep the clock in view.

One Kotlin Multiplatform rules engine compiles to an XCFramework for the Apple Watch and iPhone apps and to an AAR for the Wear OS and Android apps. Sports are data: each ruleset is a JSON file. Elapsed time comes only from monotonic clocks, and the timer state is always derived from the deadline minus now, never counted down. One design-token file generates styles for React Native, SwiftUI and Compose. Default builds are offline and collect nothing.

How we built it

Each release was a Spec Kit cycle with its own spec, plan, contracts and task list, six in all from V0 to V5. A constitution sets the non-negotiables: cue timing within 100 ms in-app, test-first engine changes, offline and private by default, and accessibility as a requirement. AGENTS.md and CLAUDE.md hand agents the hard rules, including which runtime APIs are forbidden and that match logic lives only in the engine.

Agents and a person wrote it together: 131 of the 132 commits carry a Claude co-author, and a person authored every one. Every client has a golden-cue test that plays a ruleset’s canonical script and checks each cue, and 27 validators under tools/ check rulesets, privacy, translations, QR round trips and more. CI runs on our self-hosted Woodpecker server. Pull requests were used only for CI changes.

What was hard

“Shipped” meant “the code exists.” An audit on September 7 found features with no working path. The phone’s engine had no caller, adjustable parameters moved a number and changed nothing, the complications read a key nothing wrote, and nine of fourteen translations were imported by nothing. We connected each one and added guards that fail when wiring is removed: a route-reachability test, a translation-coverage test, and a diff check on the watch string catalog.

Staying alive on the wrist. On Apple Watch the match runs on chained extended runtime sessions, with a smart-alarm fallback and a scheduled notification as backup. On Wear OS it runs as a foreground service with exact alarms. Workout-session and keep-screen-on workarounds are forbidden.

One engine behind four clients. V5 replaced the placeholder bridges with the live engine on every client. A second SwiftData container on the watch then stopped matches from starting, and only the UI test target caught it. AGENTS.md now says to run the whole watch test scheme.

By the numbers

  • 132 commits, May 5 to November 14, 2026
  • 3 pull requests (2 merged), all CI changes
  • 6 Spec Kit cycles; 559 of 594 tasks checked off
  • 133 rulesets across 17 sports, 92 of them volleyball
  • 14 languages on every client
  • 234 test files (113 TypeScript, 88 Kotlin, 33 Swift), 24 of them golden-cue tests
  • 4 platforms from 1 shared engine

Where it is now

RefClock is pre-release. The code covers V0 through V5.2. What is left is mostly outside the code: deploying the rules and telemetry backends, native-speaker review for Arabic and Hebrew, recorded voice cues (verbal cues play a beep for now), accessibility audits, a closed beta, and App Store and Play Store paperwork. An open PR moves the native Apple builds onto our Mac mini CI machine.