From df649ee1bd694461cab8bd2478977b715709bf41 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 01:02:43 +0200 Subject: [PATCH] docs(trim): extract branch/commit rules into runbook --- docs/runbooks/branch-and-commit.md | 104 +++++++++++++++++++++++++++++ docs/runbooks/deploy-vercel.md | 16 +++++ docs/runbooks/mcp-integration.md | 62 +++++++++++++++++ 3 files changed, 182 insertions(+) create mode 100644 docs/runbooks/branch-and-commit.md create mode 100644 docs/runbooks/deploy-vercel.md create mode 100644 docs/runbooks/mcp-integration.md diff --git a/docs/runbooks/branch-and-commit.md b/docs/runbooks/branch-and-commit.md new file mode 100644 index 0000000..54d5227 --- /dev/null +++ b/docs/runbooks/branch-and-commit.md @@ -0,0 +1,104 @@ +--- +title: "Branch, PR & Commit Strategy" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +when_to_read: "Before creating a branch, commit, or PR." +--- + +# Branch, PR & Commit Strategy + +## Branch & PR Strategy (STRICT — kostenbeheersing) + +> **Core rule: één branch per milestone, PR alleen na gebruikerstest** + +Elke `git push` naar een feature-branch triggert een Vercel preview-deployment. Op het huidige Hobby-account zijn die schaars en kosten geld; we minimaliseren preview-builds tot er werkelijk iets te reviewen valt. + +### Wel doen + +- Eén branch voor de hele milestone — `feat/M{N}-{slug}` (bv. `feat/M10-qr-login`); voor losse stories zonder milestone blijft `feat/ST-XXX-{slug}` geldig +- Commits accumuleren lokaal volgens de Commit Strategy hieronder — één commit per stap, ST-code in de titel +- Pushen + PR openen **pas nadat de gebruiker de milestone handmatig heeft getest en goedgekeurd** — vraag expliciet om bevestiging vóór `git push` +- Tussentijdse "klaar voor jouw test"-momenten markeren met een lokale tag of een berichtje in chat, niet met een push + +### Niet doen + +- Pushen na elke story of commit +- Een PR per story openen tijdens de implementatie +- "Just-in-case" pushen om backup te hebben — gebruik `git stash`, een lokale tag, of meerdere lokale branches +- `--force-push` om eerdere preview-builds "weg te toveren" (kost dezelfde build opnieuw bij hercreatie) +- **Direct pushen naar `main`** — die branch heeft protection rules; gebruik altijd een PR + +### Wanneer wel commit-zonder-vragen, wanneer niet + +- **Tijdens een directed sprint-flow** (Track A: `mcp__scrum4me__implement_next_story` of een expliciete *"implementeer M{N}"*-opdracht): commit-per-laag conform de Commit Strategy hieronder is impliciet geautoriseerd — niet per commit vragen +- **Bij ad-hoc / out-of-band werk** (bug-fix tussendoor, refactor, kleine wijziging op verzoek): toon de diff + voorgestelde commit-message en wacht op `"commit it"` voordat je `git commit` draait +- **`git push` is altijd expliciet** — de scope van de policy gaat over preview-builds, dus push gebeurt alleen na gebruiker-test, ongeacht commit-context + +### Uitzonderingen op de push-regel + +- Een **planning-PR** zonder code-wijzigingen (alleen docs in `docs/plans/` of `docs/`) mag direct gepusht worden — die triggert geen functional regressie en is goedkoop te bouwen +- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden (via een PR — zie boven) + +### Wanneer aanpassen + +Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) gaat: vervang deze regel door "branch + PR per story" zoals oorspronkelijk in dit document stond. Werk deze sectie bij én documenteer de wijziging in `docs/decisions/agent-instructions-history.md`. + +--- + +## Plan Mode + +- Voor simpele, goed-afgebakende file-edits: **niet** in plan mode gaan — gewoon de wijziging maken +- Reserveer plan mode voor multi-step refactors, ambigue verzoeken, of milestone-planning waarbij design-keuzes vooraf bevestigd moeten worden +- Plannen die uit plan mode komen: opslaan als `docs/plans/M{N}-{slug}.md` (zie memory `feedback_plan_location`), niet als ephemeral systeem-bestand + +--- + +## Commit Strategy (STRICT) + +> **Core rule: één commit = één verantwoordelijkheid** + +### Nooit doen + +- Database + API + UI in één commit mengen +- Feature + documentatie combineren +- Grote "alles gewijzigd" commits +- Vage berichten zoals "update stuff" + +### Verplichte structuur + +Splits werk op in logische lagen: + +1. Database / Prisma +2. API / server actions +3. UI / components +4. Config / infra +5. Documentatie + +### Commit-formaat + +``` +feat(ST-XXX): korte beschrijving +fix(ST-XXX): korte beschrijving +chore(ST-XXX): korte beschrijving +docs(ST-XXX): korte beschrijving +``` + +### Voorbeeld (verplicht patroon) + +In plaats van: + +```bash +feat: add profile system +``` + +Splits altijd op in: + +```bash +feat(ST-XXX): add user profile fields to Prisma schema +feat(ST-XXX): add avatar upload endpoint +feat(ST-XXX): add profile editor component +chore(ST-XXX): configure sharp for avatar processing +docs(ST-XXX): document profile feature +``` diff --git a/docs/runbooks/deploy-vercel.md b/docs/runbooks/deploy-vercel.md new file mode 100644 index 0000000..4344d67 --- /dev/null +++ b/docs/runbooks/deploy-vercel.md @@ -0,0 +1,16 @@ +--- +title: "Vercel Deployment" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +when_to_read: "Before deploying to Vercel or modifying cron/image/env config." +--- + +# Deployment (Vercel) + +- **Sharp** moet Linux-binaries hebben voor de Vercel-runtime: `npm i --include=optional sharp` of platform-specifieke deps configureren in `package.json` +- **Externe image hostnames** in `next.config.js` `images.remotePatterns` configureren *vóór* `next/image` op die hosts wijst — anders 500 in productie +- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/api/rest-contract.md` + relevante pattern-docs updaten +- **`CRON_SECRET`** moet als env-var op de Vercel-project-omgeving staan vóór de eerste cron-run, anders 401 op `/api/cron/*`-endpoints +- **Preflight** vóór deploy: `npm run lint && npm test && npm run build` — falende build laat een PR niet door (CI blokkeert merge per ST-610) diff --git a/docs/runbooks/mcp-integration.md b/docs/runbooks/mcp-integration.md new file mode 100644 index 0000000..bacc288 --- /dev/null +++ b/docs/runbooks/mcp-integration.md @@ -0,0 +1,62 @@ +--- +title: "MCP Integration — Scrum4Me Tools" +status: active +audience: [ai-agent] +language: nl +last_updated: 2026-05-03 +when_to_read: "When using MCP tools to interact with the Scrum4Me backlog." +--- + +# MCP-integratie + +Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd. + +## Tools beschikbaar in Claude Code (18) + +**Read / context:** +- `mcp__scrum4me__health` — service + DB ping +- `mcp__scrum4me__list_products` — producten waar de tokengebruiker toegang tot heeft +- `mcp__scrum4me__get_claude_context` — bundled product / actieve sprint / next story (met tasks) / open todos + +**Authoring (PBI/Story/Task aanmaken):** +- `mcp__scrum4me__create_pbi` — `{ product_id, title, description?, priority, sort_order? }`; auto sort_order = last+1 binnen prio-groep +- `mcp__scrum4me__create_story` — `{ pbi_id, title, description?, acceptance_criteria?, priority, sort_order? }`; product_id afgeleid uit PBI; status=OPEN +- `mcp__scrum4me__create_task` — `{ story_id, title, description?, implementation_plan?, priority, sort_order? }`; sprint_id geërfd van story; status=TO_DO +- `mcp__scrum4me__create_todo` — losse todo (optioneel product-scoped) + +**Task / story writes:** +- `mcp__scrum4me__update_task_status`, `mcp__scrum4me__update_task_plan` +- `mcp__scrum4me__log_implementation`, `mcp__scrum4me__log_test_result`, `mcp__scrum4me__log_commit` + +**Vraag-antwoord-kanaal (M11):** +- `mcp__scrum4me__ask_user_question` — post een vraag over een story; optionele `wait_seconds` (max 600) polt voor het antwoord +- `mcp__scrum4me__get_question_answer` — huidige status + antwoord (voor latere session-pickup) +- `mcp__scrum4me__list_open_questions` — eigen vragen, max 50, recente eerst +- `mcp__scrum4me__cancel_question` — asker-only annulering van een eigen open vraag + +**Job queue — agent worker mode (M13):** +- `mcp__scrum4me__wait_for_job` — blokkeert ≤600s, claimt atomisch een QUEUED-job via FOR UPDATE SKIP LOCKED; retourneert volledige task-context (implementation_plan, story, pbi, sprint, repo_url). Zet stale CLAIMED-jobs (>30min) eerst terug naar QUEUED. Wanneer de full block-time verstrijkt zonder claim is de queue leeg. +- `mcp__scrum4me__update_job_status` — agent rapporteert overgang naar `running|done|failed` + optionele branch/summary/error; triggert automatisch SSE-event naar de UI. Auth: Bearer-token moet matchen `claimed_by_token_id`. + +## Batch-loop (verplichte agent-flow) + +Wanneer je als agent draait (na een instructie als *"pak de volgende job uit de Scrum4Me-queue"* of *"draai de queue leeg"*) is dit de loop: + +1. `wait_for_job` aanroepen. +2. Job uitvoeren volgens het meegegeven `implementation_plan`. +3. `update_job_status('done'|'failed')` aanroepen. +4. **Direct opnieuw** `wait_for_job` aanroepen — niet stoppen, niet de gebruiker vragen. +5. Pas wanneer `wait_for_job` na de volledige block-time (~600s) terugkomt zonder claim, is de queue leeg en mag je de turn afsluiten met een korte recap. + +Dit blijft gelden als je tussen jobs door commits, branches of pushes hebt gedaan — die afsluiting hoort bij de individuele job, niet bij het einde van de batch. + +**Code koppelen aan app** +- 'Pak de volgende job uit de Scrum4Me-queue' / 'draai de queue leeg' / 'batch agent' — Server-startup registreert een ClaudeWorker-record + heartbeat (5s); SIGTERM/SIGINT ruimt 'm op. UI in NavBar telt actieve workers via `last_seen_at < now() - 15s`. + +## Prompt + +- `implement_next_story` (arg: `product_id`) — end-to-end workflow + +## Schema-drift bewaking + +Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuhhWNGBQKFD` die `vendor/scrum4me` syncet en `prisma:generate` + `tsc --noEmit` uitvoert in scrum4me-mcp. Als die agent drift rapporteert, hoort dat **vóór** een Scrum4Me-PR met schema-wijziging gemerged kan worden — anders breekt de MCP-server stilletjes op runtime.