Een agent makkelijke issues laten oppakken

Laat een online agent kleine, goed gespecificeerde issues zelf oppakken, bouwen, testen en mergen — zonder dat jouw laptop openstaat. Spexso stelt het auto-pick-label voor, jij bevestigt, en een runner in GitLab CI doet de rest. GitLab merget pas als de pipeline groen is.

Auto-pick staat per project standaard uit. Technische details en de volledige foutentabel staan op de designpagina Auto-pick (online runner).

Eenmalig: aanzetten

1. Zet auto-pick aan in het product:

   npx spexso autopick enable

   Of beantwoord de vraag "Enable auto-pick?" met ja tijdens /spexso-setup. Commit .spexso/config.json en merge het naar de target branch — pas dan ziet de runner het.

2. Controleer twee instellingen in het product:

   • Pipelines must succeed staat aan (Settings → Merge requests). Dát maakt de pipeline tot de echte gate.
   • De bot-user mag mergen naar de target branch (protected branch → Allowed to merge).

3. Zet het runner-project op (één keer voor alle producten, meestal door wie CI beheert) en koppel je product: een pipeline-schedule en een issue-webhook met TARGET_PROJECT=<groep/product>. De stappen staan in Setting up the runner project.

4. Commit de actuele spexso-commands in het product (npx spexso update + commit), anders draait de runner verouderde skills.

Issues klaarzetten

1. Bij /spexso-brainstorm toetst Spexso na het schrijven van de spec de rubric. Komt het issue in aanmerking, dan vraagt Claude:

   This issue qualifies for auto-pick: the online agent may build it and merge it
   after a green pipeline. Add the `auto-pick` label? (y/N)

   Alleen bij ja komt het label erop.

2. Bestaande backlog in één keer nalopen:

   npx spexso triage

   Je krijgt per stage::spec-issue het oordeel van de rubric en een y/n-vraag. Niet-geschikte issues zie je met de reden (bv. size::m not in rubric.sizes).

3. Wil je het oordeel van één issue zien?

   npx spexso autopick eligible 42

Standaard-rubric: size::xs of size::s, type bug/enhancement/tech-debt/maintenance, minstens één acceptatiecriterium, geen open blockers, en de spec noemt geen parallel.hotspots, auth/security, migraties of mta.yaml. Per project aan te passen in .spexso/config.json:

{ "autopick": { "enabled": true, "rubric": { "sizes": ["xs"] } } }

De rubric bepaalt alleen wat Spexso voorstelt — een mens bevestigt elk label.

Wat er dan gebeurt

1. Een label-wijziging (webhook) of de schedule start de runner-job voor jouw product. Er draait nooit meer dan één run per product tegelijk.
2. De runner ruimt eerst vorige runs op (de sweep, zie hieronder) en kijkt of er een issue écht klaarstaat: label, enkel stage::spec, niet toegewezen, geen open blockers. Niets te doen → de job stopt zonder één token te verbruiken.
3. Anders start claude -p "/spexso-marathon --autopick". Die werkt de issues sequentieel af: claimen (atomair via de branch), plannen, TDD-bouwen, reviewen, rebasen, volledige testsuite.
4. De MR wordt op auto-merge gezet voor exact de gepushte commit. GitLab merget zodra de pipeline groen is. De bot merget zelf nooit.
5. Bij de volgende run zet de sweep gemergede issues op stage::ship + needs::manual-test, post de testchecklist en haalt auto-pick eraf.

Je ziet het resultaat op het board: issues die door de bot zijn opgepakt, zijn toegewezen aan de bot-user; MRs dragen ai::ai-generated.

Als iets misgaat

Elke fout eindigt hetzelfde: auto-pick gaat eraf, needs::attention erop, met een note die zegt wat er misging. De bot probeert nooit zelf opnieuw. Voorbeelden: een rode pipeline, een merge-conflict, een gecrashte job, een issue waarvan de branch al bestond.

Opnieuw aan de bot geven:

1. Sluit een eventuele open MR en verwijder de branch spexso/issue-{id}.
2. Maak de assignee leeg.
3. Zet het issue terug op spec: npx spexso stage {id} spec
4. Zet het auto-pick-label opnieuw.

Debuggen: de job-artifacts van de runner bevatten marathon-log.jsonl en de observability-logs.

Zelf een auto-pick-issue oppakken

Dat kan altijd, zoals elk ander issue:

/spexso-start 42

Zodra jij het claimt, haalt /spexso-start het auto-pick-label eraf — de bot laat het dan met rust. Startte de bot het net? Dan blokkeert /spexso-start met "Issue #42 is assigned to @spexso-bot". Neem je het toch over (assignee wijzigen), dan merkt de bot dat vóór het mergen en stopt hij met een note.

Tips

• Begin met "maxPerRun": 1 in autopick tot je de eerste runs hebt gezien.
• Kostenrails: autopick.maxPerRun, autopick.maxBudgetUsd (per run) en een job-timeout van 2 uur. xs/s-issues draaien op Sonnet via modelBySize.
• Noodstop: pauzeer de schedule en de trigger in het runner-project. Definitief uitzetten: npx spexso autopick disable + commit.
• Auto-pick-runs slaan de CHANGELOG-entry, het spec-archief, de learning card en de demo-note over — die horen bij de menselijke flow. De squash-commit is het spoor.