Specgetty on Droid: je OpenSpec-changes beoordelen op je telefoon

Eerder introduceerden we specgetty, onze terminal-tool om OpenSpec-specificaties gefocust te beoordelen. De reactie die we het vaakst kregen was een variant op dezelfde vraag: leuk, maar ik zit niet de hele dag achter mijn werkstation.

Daarom is er nu specgetty-mobile.

Specs lezen op een telefoon

Code lezen op een telefoon is een slecht idee. Te veel regels, te veel context, te weinig scherm. Wie weleens een pull request op zijn mobiel heeft proberen te beoordelen, weet dat je op een gegeven moment goedkeurt zonder het echt gelezen te hebben.

Een OpenSpec-change is iets anders. Een proposal is proza. Een design is proza. Een requirement met scenario’s is een paar alinea’s gestructureerde tekst waarin staat wat het systeem hoort te doen. Dat is precies het soort materiaal dat op een klein scherm prima leest.

En dat is een van de onderschatte gevolgen van spec-driven development. Als het beoordeelmoment verschuift van de code naar de specificatie, dan verschuift het ook van “achter mijn bureau met de repo open” naar “overal waar ik tien minuten heb”. In de trein. Tussen twee meetings door. Terwijl de agent zit te bouwen.

Wat de app doet

Een OpenSpec-project bewaart zijn specificaties in een map openspec/: de huidige specs onder specs/, het werk in uitvoering onder changes/, en alles wat af is onder changes/archive/. De app kloont die repository over HTTPS en laat je alles lezen op je telefoon.

Repositories. Je voegt er een toe met de HTTPS clone-URL, door een QR-code te scannen, of door een link vanuit je browser naar de app te delen. Je hoeft de URL niet precies goed te hebben: plak een willekeurige GitHub-pagina en die wordt teruggebracht tot iets wat kloont. Elke rij toont hoeveel specs het project heeft, hoeveel changes actief en gearchiveerd zijn, en hoe ver de openstaande taken staan.

De lijst met repositories in de app. Een rij voor het project specgetty, met de clone-URL eronder. Daaronder de telling van specs, changes en openstaande taken — Elke repository toont in één regel hoe het project ervoor staat

Één repository kan ook meerdere OpenSpec-projecten bevatten, elk met een eigen openspec/-map. De app laat bij het toevoegen zien welke hij gevonden heeft en je kiest welke je wil volgen. Ze delen daarna één gekloonde kopie, dus verversen haalt de repository één keer op en werkt ze allemaal bij.

Changes. Actief en gearchiveerd in één doorzoekbare lijst. Typen matcht losjes op namen; een dubbele punt vooraan zoekt in de tekst binnen elke change en zegt welke bestanden raak waren.

Een change. Een tab per artefact dat de change daadwerkelijk heeft, gerenderd als markdown, plus de takenlijst met een vakje per taak naast de voortgang.

De changes-lijst van een project. Bovenaan een zoekveld met drie zoekmodi. Daaronder de changes, gegroepeerd in actief en gearchiveerd — De changes-lijst en een geopende change

De takenlijst van een geopende change. Bovenaan een voortgangsbalk. Per taak een vakje dat aangevinkt is of niet — De changes-lijst en een geopende change

Spec deltas: het eigenlijke reviewwerk

De functie waar het om draait is de weergave van spec deltas. Per change zie je welke requirements worden toegevoegd, gewijzigd, verwijderd of hernoemd. En bij een change die nog niet gearchiveerd is, kun je een gewijzigde requirement naast de bestaande leggen: het verschil, het origineel, en het voorstel.

Dat is de vraag die je bij het beoordelen van een wijzigingsvoorstel echt wil beantwoorden. Niet “wat staat hier”, maar “wat verandert hier ten opzichte van wat we hadden afgesproken”.

Een gewijzigde requirement in de deltaweergave. Bovenaan de keuze tussen verschil, origineel en voorstel. Daaronder de regels die weggaan in rood en de regels die erbij komen in groen — Wat een change zou veranderen aan een bestaande requirement

De kaartweergave uit de TUI is meegekomen. Een spec toont zijn purpose, zijn requirements en de bijbehorende scenario’s, elk op een eigen kaart. Één gedrag per keer, doorbladeren met je duim. Op een telefoon voelt dat nog natuurlijker dan in de terminal.

Een spec die opengaat als overzicht. Daarna wordt hij kaart voor kaart doorgebladerd, met per kaart één requirement of scenario — Één gedrag per kaart, doorbladeren met je duim

Git is het transport. Er is geen backend.

Er staat geen server tussen. Geen account bij ons, geen sync-dienst, geen kopie van je specs op een machine die wij beheren. De app kloont uit jouw repository en dat is het hele verhaal.

Private repositories worden ondersteund. Voor github.com autoriseer je de app met een korte code in je browser en kies je zelf welke repositories hij mag zien; voor andere hosts gebruik je een access token. De toegang is in beide gevallen alleen-lezen, en de inloggegevens worden versleuteld bewaard in de Android Keystore en verdwijnen samen met de repository.

Gebouwd op de specs van zijn eigen voorganger

Het leukste aan dit project zit onder de motorkap. De grammatica waarmee de app specs leest is niet opnieuw verzonnen: die staat in specgetty’s eigen openspec/specs/, wordt daar geïmplementeerd, en is vastgepind met dertien fixtures die stuk voor stuk uit een echte spec komen in plaats van verzonnen te zijn.

Die fixtures zijn overgenomen in de tests van de app. En daar bovenop een kopie van de complete openspec-tree van specgetty zelf, zoals die was op het moment van overnemen: 28 specs en 57 gearchiveerde changes met 110 deltabestanden. De parsers van de app moeten die allemaal kloppend structureren. Waar de app en specgetty van mening zouden kunnen verschillen, beslist specgetty.

Daarmee is de specificatie de koppeling tussen twee programma’s in twee verschillende talen. Dat is spec-driven development dat zijn eigen belofte waarmaakt, en het is de reden dat we erin geloven.

Dezelfde discipline zit in de release-straat. Een script draait de volledige kwaliteitspoort voordat een change gearchiveerd wordt, met een dekkingsvloer van 70 procent over de bundel en 80 procent op de parser. Een change die faalt wordt dus nooit half geshipt.

Wat er nog niet in zit

Deze eerste fase leest. Hij bewerkt niet, vinkt geen taken af, archiveert niet en pusht niet. Dat is een bewuste afbakening: eerst het lezen goed krijgen, dan pas schrijven.

Fase twee is het afvinken van taken, waarbij tasks.md wordt teruggeschreven en via JGit gecommit en gepusht. Niet gepland zijn SSH-authenticatie, achtergrondsynchronisatie, en het zoeken naar projecten ergens anders dan in openspec/ in de wortel van een repository.

Installeren

De app draait op Android 8.0 en nieuwer. De APK staat op de releasepagina op GitHub.

Uiteindelijk willen we hem via F-Droid aanbieden. Dat past bij hoe het project in elkaar zit: open source, geen tracking, geen account, en een build die dankzij de Nix-flake reproduceerbaar uit de bron te maken is. Precies wat F-Droid van een inzending verwacht.

De broncode staat op github.com/speclib/specgetty-mobile, onder de Apache 2.0-licentie. Issues en pull requests zijn welkom.

Deze app is niet gelieerd aan het OpenSpec-project.