docs(cleanup): archief verouderde plannen, backlog en root-duplicaten (#191)
* docs(cleanup): archief verouderde plannen, backlog en root-duplicaten
- 6 plans naar docs/old/plans/ (PBI-11/75/78, user-settings-store, Local github setup, lees-de-readme — laatste was verkeerde repo)
- docs/backlog/ naar docs/old/backlog/ (pre-MCP statische registry; live werk loopt via Scrum4Me-MCP)
- 6 root-level duplicaten naar docs/old/ (functional, {pbi,story,task}-dialog, product-backlog, backlog)
- 2 landing plans (niet uitgevoerd) krijgen archived: true frontmatter — blijven op plek maar uit INDEX
- scripts/generate-docs-index.mjs: skip docs/old/** + skip archived: true
- CLAUDE.md: rijen docs/backlog/, docs/plans/<key>-*.md, docs/manual/ weg; Track B-sectie verwijderd
- README.md / CHANGELOG.md / docs/plans/v1-readiness.md: link-fixes naar nieuwe locaties
Verify groen (lint + typecheck + 718 tests). docs/INDEX.md geregenereerd.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(cleanup): registreer handmatige verplaatsingen en fix referenties
- 4 plans verplaatst naar docs/old/plans/ (M10-qr-pairing-login, auto-pr-deploy-sync, docs-restructure-ai-lookup, v1-readiness)
- 3 archive-plans verplaatst naar docs/old/plans/ (archive-map nu leeg)
- ST-1114-copilot-reviews + 3 research-docs naar nieuwe docs/Ideas/ map
- Duplicaat docs/old/2026-04-27-m8-realtime-solo.md verwijderd (origineel zit in docs/old/plans/)
- Link-fixes naar nieuwe locaties:
- CHANGELOG.md → docs/old/plans/v1-readiness.md
- docs/runbooks/deploy-control.md → docs/old/plans/auto-pr-deploy-sync.md (2x)
- docs/runbooks/worker-idempotency.md → docs/old/plans/auto-pr-deploy-sync.md
- docs/plans/docs-restructure-pbi-spec.md → docs/old/plans/docs-restructure-ai-lookup.md (4x text + 2x href)
- docs/INDEX.md geregenereerd (96 docs, was 100)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser
GitHub
parent
d587be2fb3
commit
b39c3ec2e1
36 changed files with 1068 additions and 49 deletions
|
|
@ -67,7 +67,7 @@ launch-ready state na de v1-readiness-checklist (Now + Before-launch items).
|
|||
edit-iconen op PBI/story/task-rijen. ([#79](https://github.com/madhura68/Scrum4Me/pull/79))
|
||||
- Edit-icoon op product-card in dashboard (consistent met PBI/story/task-pattern).
|
||||
([#83](https://github.com/madhura68/Scrum4Me/pull/83))
|
||||
- v1.0 readiness checklist in `docs/plans/v1-readiness.md`.
|
||||
- v1.0 readiness checklist in `docs/old/plans/v1-readiness.md`.
|
||||
([#82](https://github.com/madhura68/Scrum4Me/pull/82))
|
||||
|
||||
### Changed
|
||||
|
|
@ -95,7 +95,7 @@ Initiële stabilisatie-release.
|
|||
## Pre-0.3.x
|
||||
|
||||
Foundation-werk (M0 t/m M8) is niet retroactief in dit changelog opgenomen.
|
||||
Voor de volledige milestone-historie zie [docs/backlog/index.md](./docs/backlog/index.md).
|
||||
Voor de volledige milestone-historie zie [docs/old/backlog/index.md](./docs/old/backlog/index.md).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -19,19 +19,15 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ
|
|||
| `docs/INDEX.md` | Gegenereerde index van alle docs — begin hier |
|
||||
| `docs/specs/functional.md` | Acceptatiecriteria, user flows |
|
||||
| `docs/architecture.md` | Breadcrumb → 6 topische arch-bestanden |
|
||||
| `docs/backlog/index.md` | Implementatievolgorde, "done when"-criteria |
|
||||
| `docs/api/rest-contract.md` | REST API contract voor Claude Code |
|
||||
| `docs/design/styling.md` | **Lees vóór elk component** — MD3-tokens, shadcn |
|
||||
| `docs/plans/<key>-*.md` | Implementatieplan per milestone |
|
||||
| `docs/adr/` | Architecture Decision Records — tech-keuzes (base-ui vs Radix, sort-order, demo-policy, …) |
|
||||
| `docs/manual/` | 7-delige gebruiks- en operationele handleiding (workflow, git, docker, troubleshooting) |
|
||||
| `docs/architecture/` | 6 topische architecture-bestanden (data-model, auth, sprint-execution, …) — uitwerking van `docs/architecture.md` |
|
||||
|
||||
---
|
||||
|
||||
## Hoe werk vinden
|
||||
|
||||
**Track A — MCP (aanbevolen):**
|
||||
1. Branch aanmaken: `git checkout -b feat/<batch-slug>` — nog **geen** `gh pr create`
|
||||
2. `mcp__scrum4me__get_claude_context` → pak de next story
|
||||
3. Voer taken uit in `sort_order`; update status per taak
|
||||
|
|
@ -41,11 +37,6 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ
|
|||
7. Herhaal stap 2–6 per story; branch blijft dezelfde
|
||||
8. Queue leeg → `git push -u origin <branch>` + `gh pr create`
|
||||
|
||||
**Track B — manueel:**
|
||||
1. Lees taak in `docs/backlog/index.md`
|
||||
2. Zoek spec in `docs/specs/functional.md`
|
||||
3. Lees patroon + styling → bouw → verifieer → vraag bevestiging → commit
|
||||
|
||||
Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbooks/mcp-integration.md)
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -287,5 +287,4 @@ De productieomgeving is gericht op Vercel + Neon.
|
|||
|
||||
- [Functionele specificatie](docs/specs/functional.md)
|
||||
- [Technische architectuur](docs/architecture.md)
|
||||
- [Backlog](docs/backlog/index.md)
|
||||
- [Agent-instructie audit](docs/decisions/agent-instructions-history.md)
|
||||
|
|
|
|||
|
|
@ -39,44 +39,23 @@ Auto-generated on 2026-05-11 from front-matter and headings.
|
|||
|
||||
| Title | Status | Updated |
|
||||
|---|---|---|
|
||||
| [Plan — Auto-PR + selectieve deploy-controle + sync-zicht (end-to-end batch flow)](./plans/auto-pr-deploy-sync.md) | — | — |
|
||||
| [Docs-restructuur — geoptimaliseerd voor AI-lookup](./plans/docs-restructure-ai-lookup.md) | proposal | 2026-05-02 |
|
||||
| [PBI Bulk-Create Spec — Docs-Restructure for AI-Optimized Lookup](./plans/docs-restructure-pbi-spec.md) | done | 2026-05-03 |
|
||||
| [Plan: model + mode-selectie per ClaudeJob-kind](./plans/job-model-selection.md) | — | — |
|
||||
| [Landing v2 — lokaal & veilig + architectuurdiagram](./plans/landing-local-first.md) | active | 2026-05-03 |
|
||||
| [Landing v3 — van idee tot pull request](./plans/landing-v3-idea-flow.md) | active | 2026-05-04 |
|
||||
| [Scrum4Me-Research — Zustand rearchitecture (reset + execute)](./plans/lees-de-readme-md-validated-book.md) | — | — |
|
||||
| [Verbeterplan load/render Product Backlog, Sprint en Solo](./plans/load-render-improvement-plan-2026-05-10.md) | draft | 2026-05-10 |
|
||||
| [Advies — Zelf een Git-platform hosten naast of in plaats van GitHub](./plans/Local github setup.md) | — | — |
|
||||
| [M10 — Password-loze inlog via QR-pairing](./plans/M10-qr-pairing-login.md) | active | 2026-05-03 |
|
||||
| [M11 — Claude vraagt, gebruiker antwoordt](./plans/M11-claude-questions.md) | active | 2026-05-03 |
|
||||
| [M12 — Idea entity + Grill/Plan Claude jobs](./plans/M12-ideas.md) | planned | — |
|
||||
| [M9 — Actief Product Backlog](./plans/M9-active-product-backlog.md) | active | 2026-05-03 |
|
||||
| [PBI-11 — Mobile-shell met landscape-lock (settings + backlog + solo)](./plans/PBI-11-mobile-shell.md) | — | — |
|
||||
| [PBI-75 — Sprint task-edit client-side via workspace-store](./plans/PBI-75-sprint-task-edit-store.md) | — | — |
|
||||
| [PBI-78 — Cost-analyse widget op Insights-pagina](./plans/PBI-78-cost-analysis-widget.md) | — | — |
|
||||
| [PBI-79: Product Backlog workflow — sprint-membership via vinkjes](./plans/PBI-79-backlog-sprint-workflow.md) | — | — |
|
||||
| [Queue-loop verplaatsen van Claude naar runner](./plans/queue-loop-extraction.md) | — | — |
|
||||
| [Advies - SprintRun, PR en worktree lifecycle als state machines](./plans/sprint-pr-worktree-state-machines.md) | draft | 2026-05-06 |
|
||||
| [ST-1109 — PBI krijgt een status (Ready / Blocked / Done)](./plans/ST-1109-pbi-status.md) | active | 2026-05-03 |
|
||||
| [ST-1110 — Demo gebruiker read-only](./plans/ST-1110-demo-readonly.md) | active | 2026-05-03 |
|
||||
| [ST-1111 — Voer uit-knop met Claude Code job queue](./plans/ST-1111-claude-job-trigger.md) | active | 2026-05-03 |
|
||||
| [ST-1114 — Copilot reviews op dashboard](./plans/ST-1114-copilot-reviews.md) | active | 2026-05-03 |
|
||||
| [Plan: wekelijkse sync van `model_prices` (PBI-66 / ST-1296)](./plans/sync-model-prices.md) | — | — |
|
||||
| [Tweede Claude Agent — Planning Agent](./plans/tweede-claude-agent-planning.md) | proposal | 2026-05-03 |
|
||||
| [User-settings store (DB-backed user prefs)](./plans/user-settings-store.md) | draft | 2026-05-10 |
|
||||
| [Scrum4Me — v1.0 readiness](./plans/v1-readiness.md) | active | 2026-05-04 |
|
||||
| [Zustand store rearchitecture - active context, realtime en resync](./plans/zustand-store-rearchitecture.md) | ready-to-execute | 2026-05-09 |
|
||||
| [Zustand workspace-store implementatieplan (PBI-74)](./plans/zustand-workspace-store-implementation.md) | in-progress | 2026-05-10 |
|
||||
|
||||
### Archive
|
||||
|
||||
| Title | Updated |
|
||||
|---|---|
|
||||
| [CLAUDE.md workflow-update na M7 + ST-509/511/512/513](./plans/archive/2026-04-27-claude-md-workflow-update.md) | 2026-05-03 |
|
||||
| [Herbruikbaar scripts/insert-milestone.ts](./plans/archive/2026-04-27-insert-milestone-tool.md) | 2026-05-03 |
|
||||
| [Realtime updates voor Solo Paneel (M8)](./plans/archive/2026-04-27-m8-realtime-solo.md) | 2026-05-03 |
|
||||
|
||||
## Patterns
|
||||
|
||||
| Title | Status | Updated |
|
||||
|
|
@ -112,15 +91,15 @@ Auto-generated on 2026-05-11 from front-matter and headings.
|
|||
| [Project Structure, Stores, Realtime & Job Queue](./architecture/project-structure.md) | `architecture/project-structure.md` | active | 2026-05-08 |
|
||||
| [QR-pairing Login Flow](./architecture/qr-pairing.md) | `architecture/qr-pairing.md` | active | 2026-05-03 |
|
||||
| [Sprint execution modes — PER_TASK vs SPRINT_BATCH](./architecture/sprint-execution-modes.md) | `architecture/sprint-execution-modes.md` | active | 2026-05-07 |
|
||||
| [Scrum4Me — Implementatie Backlog](./backlog.md) | `backlog.md` | active | 2026-05-03 |
|
||||
| [Scrum4Me — Implementatie Backlog](./backlog/index.md) | `backlog/index.md` | active | 2026-05-03 |
|
||||
| [DevPlanner — Product Backlog](./backlog/product-historical.md) | `backlog/product-historical.md` | active | 2026-05-03 |
|
||||
| [Agent Instruction Audit](./decisions/agent-instructions-history.md) | `decisions/agent-instructions-history.md` | active | 2026-05-03 |
|
||||
| [Scrum4Me — Styling & Design System](./design/styling.md) | `design/styling.md` | active | 2026-05-03 |
|
||||
| [Docker smoke test — task 1](./docker-smoke/2-mei-task-1.md) | `docker-smoke/2-mei-task-1.md` | done | 2026-05-03 |
|
||||
| [Docker smoke test — task 2](./docker-smoke/2-mei-task-2.md) | `docker-smoke/2-mei-task-2.md` | done | 2026-05-03 |
|
||||
| [Scrum4Me — Functionele Specificatie](./functional.md) | `functional.md` | active | 2026-05-03 |
|
||||
| [Scrum4Me — Glossary](./glossary.md) | `glossary.md` | active | 2026-05-08 |
|
||||
| [Onderzoek — AI-gedreven programmeren en Scrum planning](./Ideas/ai-driven-scrum-planning-research.md) | `Ideas/ai-driven-scrum-planning-research.md` | draft | 2026-05-11 |
|
||||
| [Installatieplan — Beelink Ubuntu Scrum4Me server en worker-aanpassingen](./Ideas/beelink-scrum4me-server-install-and-worker-plan.md) | `Ideas/beelink-scrum4me-server-install-and-worker-plan.md` | draft | 2026-05-10 |
|
||||
| [Advies — Product Backlog en Sprint-pagina workflow](./Ideas/sprint-page-backlog-relationship-research.md) | `Ideas/sprint-page-backlog-relationship-research.md` | draft | 2026-05-11 |
|
||||
| [ST-1114 — Copilot reviews op dashboard](./Ideas/ST-1114-copilot-reviews.md) | `Ideas/ST-1114-copilot-reviews.md` | active | 2026-05-03 |
|
||||
| [Overview](./manual/01-overview.md) | `manual/01-overview.md` | active | 2026-05-07 |
|
||||
| [Statuses & Transitions](./manual/02-statuses-and-transitions.md) | `manual/02-statuses-and-transitions.md` | active | 2026-05-07 |
|
||||
| [Git Workflow](./manual/03-git-workflow.md) | `manual/03-git-workflow.md` | active | 2026-05-07 |
|
||||
|
|
@ -130,9 +109,7 @@ Auto-generated on 2026-05-11 from front-matter and headings.
|
|||
| [Scrum4Me Developer Manual](./manual/index.md) | `manual/index.md` | active | 2026-05-07 |
|
||||
| [Scrum4Me — Styling & Design System](./md3-color-scheme.md) | `md3-color-scheme.md` | active | 2026-05-03 |
|
||||
| [Obsidian as Personal Authoring Layer](./obsidian-authoring.md) | `obsidian-authoring.md` | active | 2026-05-02 |
|
||||
| [PbiDialog Profiel](./pbi-dialog.md) | `pbi-dialog.md` | active | 2026-05-03 |
|
||||
| [DevPlanner — User Personas](./personas.md) | `personas.md` | active | 2026-05-03 |
|
||||
| [DevPlanner — Product Backlog](./product-backlog.md) | `product-backlog.md` | active | 2026-05-03 |
|
||||
| [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 |
|
||||
| [Realtime smoke-checklist — PBI / Story / Task](./realtime-smoke.md) | `realtime-smoke.md` | active | 2026-05-03 |
|
||||
| [Caveman plan — Beelink naar Ubuntu Scrum4Me server](./recommendations/beelink-ubuntu-scrum4me-server-caveman-plan.md) | `recommendations/beelink-ubuntu-scrum4me-server-caveman-plan.md` | draft | 2026-05-09 |
|
||||
|
|
@ -147,6 +124,4 @@ Auto-generated on 2026-05-11 from front-matter and headings.
|
|||
| [MCP Integration — Scrum4Me Tools](./runbooks/mcp-integration.md) | `runbooks/mcp-integration.md` | active | 2026-05-08 |
|
||||
| [v1.0 Smoke Test Checklist](./runbooks/v1-smoke-test.md) | `runbooks/v1-smoke-test.md` | active | 2026-05-04 |
|
||||
| [Worker idempotency & job-status protocol](./runbooks/worker-idempotency.md) | `runbooks/worker-idempotency.md` | active | 2026-05-09 |
|
||||
| [StoryDialog Profiel](./story-dialog.md) | `story-dialog.md` | active | 2026-05-03 |
|
||||
| [TaskDialog Profiel](./task-dialog.md) | `task-dialog.md` | active | 2026-05-03 |
|
||||
| [Scrum4Me — API Test Plan](./test-plan.md) | `test-plan.md` | active | 2026-05-03 |
|
||||
|
|
|
|||
306
docs/Ideas/ai-driven-scrum-planning-research.md
Normal file
306
docs/Ideas/ai-driven-scrum-planning-research.md
Normal file
|
|
@ -0,0 +1,306 @@
|
|||
---
|
||||
title: "Onderzoek — AI-gedreven programmeren en Scrum planning"
|
||||
status: draft
|
||||
audience: [product, ai-agent]
|
||||
language: nl
|
||||
last_updated: 2026-05-11
|
||||
---
|
||||
|
||||
# Onderzoek — AI-gedreven programmeren en Scrum planning
|
||||
|
||||
## Vraag
|
||||
|
||||
Wat is het effect van AI-assisted / AI-driven programming op de manier waarop we Scrum toepassen, als werk niet meer in 1-2 weekse sprints hoeft te worden gepland maar in meerdere uitvoercycli per dag kan worden gerealiseerd? Wat gebeurt er met burndown, velocity en planning als tokengebruik, verificatie en agent-efficiency belangrijker worden?
|
||||
|
||||
## Korte conclusie
|
||||
|
||||
AI maakt Scrum niet overbodig, maar verandert waar Scrum op moet sturen.
|
||||
|
||||
Traditionele sprintplanning gebruikt vaak velocity/story points als proxy voor menselijke uitvoercapaciteit. In AI-gedreven ontwikkeling wordt menselijke typ-/bouwtijd veel minder voorspelbaar als bottleneck. De nieuwe bottlenecks zijn:
|
||||
|
||||
- helderheid van productbeslissingen;
|
||||
- kwaliteit van backlog-items en acceptatiecriteria;
|
||||
- beschikbare context voor agents;
|
||||
- verificatiecapaciteit: tests, review, security, deploy;
|
||||
- tokenkosten en modelkeuze;
|
||||
- rework door foutieve of half-passende AI-output.
|
||||
|
||||
Daarom moet planning verschuiven van "hoeveel story points kunnen we in twee weken doen?" naar "welke waardevolle hypothese kunnen we nu veilig laten uitvoeren, verifieren en leren, binnen een token- en reviewbudget?"
|
||||
|
||||
## Wat de bronnen laten zien
|
||||
|
||||
### 1. Het empirische bewijs is gemengd
|
||||
|
||||
Onderzoek naar Copilot liet in een gecontroleerde programmeertaak zien dat deelnemers met Copilot de taak 55,8% sneller voltooiden. Een latere Microsoft-studie met drie field experiments bij 4.867 developers vond gemiddeld 26,08% meer voltooide taken bij developers met AI-code-completion.
|
||||
|
||||
Tegelijk vond METR in 2025 in een realistische RCT met ervaren open-source developers dat AI-tools taken juist 19% langzamer maakten. De taken waren echte issues in grote codebases die developers goed kenden. METR waarschuwt zelf tegen te brede generalisatie, maar het resultaat is belangrijk: AI-snelheid hangt sterk af van taaktype, codebase-context, kwaliteitslat en meetmethode. In 2026 gaf METR bovendien aan dat het meten van AI-uplift lastiger wordt doordat developers liever niet meer zonder AI werken en doordat sommige developers meerdere agents tegelijk gebruiken.
|
||||
|
||||
Implicatie: Scrum4Me moet geen vaste productiviteitsfactor aannemen. Meet per product, per agent-run en per taaktype.
|
||||
|
||||
### 2. DORA: AI is een versterker, geen oplossing
|
||||
|
||||
DORA 2025 concludeert dat AI vooral een amplifier is: het versterkt bestaande sterke en zwakke punten. Google rapporteert bijna universele adoptie, veel ervaren individuele productiviteitswinst, maar ook een vertrouwensparadox en complexere effecten op organisatorische performance.
|
||||
|
||||
DORA's AI Capabilities Model noemt zeven randvoorwaarden die AI-effecten versterken:
|
||||
|
||||
- duidelijke AI-stance/policy;
|
||||
- gezonde data-ecosystemen;
|
||||
- AI-toegankelijke interne data;
|
||||
- sterke version-control-praktijken;
|
||||
- kleine batches;
|
||||
- user-centric focus;
|
||||
- kwalitatieve interne platforms.
|
||||
|
||||
Voor Scrum betekent dit: de sprint moet niet groter worden omdat agents sneller code schrijven. De batch moet kleiner worden, met scherpere feedback.
|
||||
|
||||
### 3. Agile verschuift naar outcome- en governance-gedreven planning
|
||||
|
||||
Digital.ai's 18th State of Agile beschrijft AI als een verschuiving van ondersteunende tool naar orchestrator van de delivery lifecycle. Tegelijk noemt het rapport hogere ROI-druk, governance-lag en de noodzaak om Agile-investeringen aan meetbare business outcomes te koppelen.
|
||||
|
||||
Implicatie: velocity en burndown zijn onvoldoende als hoofdmetrics. Ze laten activiteit zien, geen waarde, geen kosten en geen risico.
|
||||
|
||||
### 4. Tokengebruik wordt economisch relevant, maar is geen doel op zichzelf
|
||||
|
||||
Stanford Digital Economy Lab vond in 2026 dat agentic coding tasks veel token-intensiever zijn dan code chat/reasoning, dat inputtokens de kosten domineren, dat runs op dezelfde taak tot 30x kunnen verschillen in tokengebruik, en dat meer tokens niet automatisch meer accuracy opleveren.
|
||||
|
||||
Jellyfish analyseerde 12.000 developers bij 200 bedrijven en vond dat meer tokengebruik wel met meer output correleert, maar disproportioneel duurder wordt. De topgebruikers haalden ongeveer twee keer zoveel PR-throughput, maar met ongeveer tien keer zoveel tokens per PR.
|
||||
|
||||
Implicatie: tokenusage is een cost/efficiency-signaal, geen prestatiebadge. "Tokenmaxxing" is net zo gevaarlijk als velocity maximaliseren.
|
||||
|
||||
## Wat verandert aan Scrum?
|
||||
|
||||
### Sprint
|
||||
|
||||
De Sprint blijft nuttig als container voor focus, inspectie en adaptatie. Maar bij AI-gedreven werk is een sprint minder een capaciteitsmandje voor menselijke arbeid en meer een beslis- en leerhorizon.
|
||||
|
||||
Advies:
|
||||
|
||||
- Gebruik "Sprint" voor productfocus en Sprint Goal.
|
||||
- Gebruik "AI runs" of "execution cycles" binnen de sprint voor 1-4 uitvoercycli per dag.
|
||||
- Noem 4 cycli per dag liever geen 4 Scrum-sprints, tenzij je ook echt 4 keer Sprint Planning, Review en Retrospective wilt doen. Dat levert ceremonie-overhead op.
|
||||
|
||||
### Sprint Planning
|
||||
|
||||
Planning verschuift van effort forecast naar control loop.
|
||||
|
||||
Oude vraag:
|
||||
|
||||
- Hoeveel werk kunnen we deze sprint doen?
|
||||
|
||||
Nieuwe vraag:
|
||||
|
||||
- Welke waardevolle slice is klaar voor agent-uitvoering?
|
||||
- Welke context en tests maken het veilig?
|
||||
- Welk model/mode/budget past bij risico en complexiteit?
|
||||
- Hoe weten we binnen 30-120 minuten of dit goed genoeg is?
|
||||
- Wat is de maximale token- en reviewspend voor deze poging?
|
||||
|
||||
### Daily Scrum
|
||||
|
||||
Daily Scrum wordt minder statusmeeting en meer flow-control:
|
||||
|
||||
- Welke agent-runs zijn afgerond, geblokkeerd of failed?
|
||||
- Waar zit de verificatiequeue?
|
||||
- Welke Product Owner-beslissing ontbreekt?
|
||||
- Welke context ontbreekt waardoor tokens of rework oplopen?
|
||||
- Moeten we scope heronderhandelen zonder het Sprint Goal te beschadigen?
|
||||
|
||||
Bij 4 runs per dag kan een korte "run review" na elke run de Daily Scrum deels vervangen.
|
||||
|
||||
### Sprint Review
|
||||
|
||||
Review wordt frequenter en meer outcome-gericht:
|
||||
|
||||
- Wat is echt geaccepteerd en bruikbaar?
|
||||
- Welke hypothese is gevalideerd?
|
||||
- Wat is alleen code-output maar nog geen waarde?
|
||||
- Welke user feedback of runtime data hebben we?
|
||||
|
||||
### Retrospective
|
||||
|
||||
Retrospective moet expliciet AI-systemen verbeteren:
|
||||
|
||||
- Welke prompts, contextbestanden of specs verminderden rework?
|
||||
- Welke modelkeuzes waren te duur of te zwak?
|
||||
- Waar faalden tests/reviews te laat?
|
||||
- Welke taken waren slecht voorbereid voor agents?
|
||||
- Waar waren menselijke beslissingen de bottleneck?
|
||||
|
||||
## Nieuwe planningshiërarchie
|
||||
|
||||
Een praktisch model voor Scrum4Me:
|
||||
|
||||
| Laag | Cadans | Doel | Output |
|
||||
|---|---:|---|---|
|
||||
| Product Goal / roadmap | weken-maanden | richting en waarde | product outcomes, prioriteiten |
|
||||
| Sprint | 1 dag tot 1 week | focus en leerdoel | Sprint Goal, selected PBIs/stories, budget |
|
||||
| AI execution run | 1-3 uur | concrete slice bouwen/verifieren | PR/diff, testresultaat, token/cost telemetry |
|
||||
| Agent job | minuten-uren | taak uitvoeren | logs, patch, status, vragen |
|
||||
|
||||
Voor solo/kleine teams met Scrum4Me is een dag-sprint of week-sprint met meerdere AI runs realistischer dan 4 volledige Scrum-sprints per dag.
|
||||
|
||||
## Nieuwe metrics
|
||||
|
||||
### Behoud, maar herinterpreteer
|
||||
|
||||
- Lead time: idee/story -> geaccepteerde productie-wijziging.
|
||||
- Cycle time: taak/run start -> done.
|
||||
- Deployment frequency.
|
||||
- Change failure rate.
|
||||
- MTTR.
|
||||
- Escaped defects.
|
||||
|
||||
Deze blijven belangrijker dan velocity.
|
||||
|
||||
### Vervang velocity als hoofdmetric
|
||||
|
||||
Velocity/story points kunnen nog gespreksmateriaal zijn voor complexiteit en onzekerheid, maar niet meer als centrale capaciteitsmetric.
|
||||
|
||||
Betere hoofdmetrics:
|
||||
|
||||
- accepted increments per dag/week;
|
||||
- validated outcomes per week;
|
||||
- lead time per PBI/story;
|
||||
- verification queue time;
|
||||
- change failure rate na AI-runs;
|
||||
- rework rate na review;
|
||||
- human intervention rate;
|
||||
- agent first-pass success rate.
|
||||
|
||||
### Voeg token-economie toe
|
||||
|
||||
Nuttige tokenmetrics:
|
||||
|
||||
- tokens per accepted task;
|
||||
- tokens per merged PR;
|
||||
- tokens per validated outcome;
|
||||
- tokens per failed/abandoned run;
|
||||
- input/output/cache-token mix;
|
||||
- cost per accepted task;
|
||||
- cost per defect fixed;
|
||||
- review minutes per 1M tokens;
|
||||
- token spend by model/mode/job-kind;
|
||||
- wasted tokens: output niet gebruikt, failed loops, repeated context discovery.
|
||||
|
||||
Belangrijke waarschuwing: tokens zijn een input-cost, geen output-value. Gebruik ze als budget en efficiency-signaal, niet als score.
|
||||
|
||||
### Nieuwe samengestelde metric
|
||||
|
||||
Voor Scrum4Me zou een nuttige metric kunnen zijn:
|
||||
|
||||
```text
|
||||
AI Delivery Efficiency =
|
||||
accepted value units
|
||||
/ (token cost + human review time + elapsed time + rework penalty)
|
||||
```
|
||||
|
||||
In de praktijk kan dit simpeler:
|
||||
|
||||
```text
|
||||
accepted_tasks_per_euro
|
||||
accepted_tasks_per_1M_tokens
|
||||
merged_PRs_per_review_hour
|
||||
validated_outcomes_per_day
|
||||
```
|
||||
|
||||
## Definition of Ready voor AI
|
||||
|
||||
Een story/task is AI-ready als:
|
||||
|
||||
- het gewenste gedrag concreet is;
|
||||
- acceptatiecriteria testbaar zijn;
|
||||
- relevante files, patronen en docs bekend of vindbaar zijn;
|
||||
- non-goals en scopegrenzen expliciet zijn;
|
||||
- risico duidelijk is: laag/middel/hoog;
|
||||
- vereiste verificatie bekend is;
|
||||
- tokenbudget/model/mode is gekozen;
|
||||
- open productvragen zijn beantwoord of expliciet buiten scope gezet.
|
||||
|
||||
## Definition of Done voor AI
|
||||
|
||||
Done betekent niet "agent heeft code geschreven". Done betekent:
|
||||
|
||||
- diff/PR is geaccepteerd;
|
||||
- tests/lint/typecheck/build passend bij risico zijn groen;
|
||||
- security/privacy/demo-mode checks zijn gedaan waar relevant;
|
||||
- menselijke review is gedaan voor risicovolle of user-facing wijzigingen;
|
||||
- tokenusage/cost is gelogd;
|
||||
- rework/lessons zijn teruggekoppeld naar prompt, docs of backlog;
|
||||
- productwaarde is zichtbaar of meetbaar.
|
||||
|
||||
## Voorstel voor Scrum4Me planning
|
||||
|
||||
### 1. Sprint als focuscontainer
|
||||
|
||||
Maak een sprint niet langer primair een verzameling werk voor 1-2 weken, maar een focuscontainer:
|
||||
|
||||
- Sprint Goal;
|
||||
- geselecteerde PBI's/stories;
|
||||
- AI-run budget;
|
||||
- verificatie-WIP-limiet;
|
||||
- risico-policy.
|
||||
|
||||
### 2. AI Runs binnen de sprint
|
||||
|
||||
Voeg of gebruik een concept als `SprintRun`:
|
||||
|
||||
- `PLANNED -> RUNNING -> VERIFYING -> ACCEPTED | REWORK | FAILED | ABANDONED`
|
||||
- gekoppelde `ClaudeJob`s / agent jobs;
|
||||
- model/mode snapshot;
|
||||
- tokenbudget en werkelijk tokengebruik;
|
||||
- affected stories/tasks;
|
||||
- testresultaat;
|
||||
- reviewbeslissing.
|
||||
|
||||
### 3. Planningproces per run
|
||||
|
||||
1. Selecteer een kleine slice uit de Sprint Backlog.
|
||||
2. Controleer AI-ready criteria.
|
||||
3. Kies model/mode/tokenbudget.
|
||||
4. Start agent jobs.
|
||||
5. Verzamel patch, logs, testresultaten en tokenusage.
|
||||
6. Verifieer.
|
||||
7. Accepteer, stuur terug voor rework, of stop de run.
|
||||
8. Update backlog en metrics.
|
||||
|
||||
### 4. Dashboard-shift
|
||||
|
||||
Vervang klassieke burndown als primaire grafiek door:
|
||||
|
||||
- token burnup vs accepted outcomes;
|
||||
- verification queue;
|
||||
- accepted/rework/failed runs;
|
||||
- lead time distribution;
|
||||
- cost per accepted task;
|
||||
- change failure / rollback rate;
|
||||
- remaining uncertainty per Sprint Goal.
|
||||
|
||||
Burndown kan blijven als "remaining selected stories/tasks", maar niet als performance-meter.
|
||||
|
||||
## Productimplicaties voor Scrum4Me
|
||||
|
||||
1. Voeg token/cost telemetry toe aan `ClaudeJob` en `SprintRun`.
|
||||
2. Maak AI-run planning zichtbaar op de Sprint-pagina.
|
||||
3. Voeg `AI Ready` checks toe aan story/task dialogs of een planning pane.
|
||||
4. Maak verification WIP expliciet: niet meer agents starten dan je kunt verifieren.
|
||||
5. Voeg budgetrails toe: per sprint, per run, per task, per model.
|
||||
6. Rapporteer tokenusage altijd naast outcome: token-only dashboards sturen verkeerd gedrag.
|
||||
7. Maak retrospectives data-driven: prompt/context/model/test-strategie verbeteren.
|
||||
|
||||
## Bronnen
|
||||
|
||||
- Scrum Guide 2020 — Sprint Planning, Sprint Backlog, Sprint Goal: https://scrumguides.org/scrum-guide.html
|
||||
- Microsoft Research — GitHub Copilot controlled experiment: https://www.microsoft.com/en-us/research/publication/the-impact-of-ai-on-developer-productivity-evidence-from-github-copilot/
|
||||
- Microsoft Research — three field experiments, 4.867 developers: https://www.microsoft.com/en-us/research/publication/the-effects-of-generative-ai-on-high-skilled-work-evidence-from-three-field-experiments-with-software-developers/
|
||||
- METR 2025 — experienced open-source developer RCT: https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/
|
||||
- METR 2026 — measurement redesign and concurrent-agent measurement issues: https://metr.org/blog/2026-02-24-uplift-update/
|
||||
- DORA 2025 — State of AI-assisted Software Development: https://dora.dev/research/2025/dora-report/
|
||||
- Google Research publication page for DORA 2025: https://research.google/pubs/dora-2025-state-of-ai-assisted-software-development-report/
|
||||
- Google Cloud — DORA AI Capabilities Model: https://cloud.google.com/blog/products/ai-machine-learning/introducing-doras-inaugural-ai-capabilities-model/
|
||||
- Google blog summary of DORA 2025: https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
|
||||
- Digital.ai — 18th State of Agile press release: https://digital.ai/press-releases/digital-ais-18th-state-of-agile-report-marks-the-start-of-the-fourth-wave-of-software-delivery/
|
||||
- Stanford Digital Economy Lab — token consumption in agentic coding tasks: https://digitaleconomy.stanford.edu/publication/how-do-ai-agents-spend-your-money-analyzing-and-predicting-token-consumption-in-agentic-coding-tasks/
|
||||
- GitHub Docs — Copilot usage metrics: https://docs.github.com/en/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/copilot-usage-metrics
|
||||
- Jellyfish — tokenmaxxing and token ROI analysis: https://jellyfish.co/blog/is-tokenmaxxing-cost-effective-new-data-from-jellyfish-explains/
|
||||
- Microsoft Research — LLM metric framework and token utilization: https://www.microsoft.com/en-us/research/articles/how-to-evaluate-llms-a-complete-metric-framework/
|
||||
|
||||
605
docs/Ideas/beelink-scrum4me-server-install-and-worker-plan.md
Normal file
605
docs/Ideas/beelink-scrum4me-server-install-and-worker-plan.md
Normal file
|
|
@ -0,0 +1,605 @@
|
|||
---
|
||||
title: "Installatieplan — Beelink Ubuntu Scrum4Me server en worker-aanpassingen"
|
||||
status: draft
|
||||
audience: [maintainer, operator, ai-agent]
|
||||
language: nl
|
||||
last_updated: 2026-05-10
|
||||
---
|
||||
|
||||
# Installatieplan — Beelink Ubuntu Scrum4Me server en worker-aanpassingen
|
||||
|
||||
## Doel
|
||||
|
||||
Deze notitie beschrijft de huidige Beelink-installatie en het vervolgplan om de Scrum4Me workers geschikt te maken voor drie rollen:
|
||||
|
||||
```text
|
||||
worker-idea
|
||||
worker-implementation
|
||||
worker-orchestrator
|
||||
```
|
||||
|
||||
De server draait nu als LAN-host voor Scrum4Me. Productie-internettoegang met domein en HTTPS is nog een latere stap.
|
||||
|
||||
## Hardware
|
||||
|
||||
| Onderdeel | Waarde |
|
||||
|---|---|
|
||||
| Machine | Beelink mini-PC |
|
||||
| CPU | Intel Core i5-12450H |
|
||||
| RAM zichtbaar in Ubuntu | 16 GB |
|
||||
| Max RAM volgens hardware | 32 GB |
|
||||
| Disk | 468 GB bruikbaar na Ubuntu-installatie |
|
||||
| IP | `192.168.0.154` |
|
||||
|
||||
Opmerking: Ubuntu ziet momenteel ongeveer 16 GB RAM. De hardware meldt een maximum van 32 GB, maar dat betekent niet dat 32 GB bruikbaar/geplaatst is.
|
||||
|
||||
## Huidige Installatie
|
||||
|
||||
### Ubuntu
|
||||
|
||||
Ubuntu Server is geïnstalleerd op de hele disk.
|
||||
|
||||
Belangrijke keuzes:
|
||||
|
||||
- Ubuntu Server 24.04 LTS.
|
||||
- Geen Ubuntu Desktop.
|
||||
- Geen LVM.
|
||||
- Geen aparte GPU-drivers.
|
||||
- Geen Windows dual boot meer.
|
||||
- Hostname: `scrum4me-server`.
|
||||
- Sleep/hibernate uitgeschakeld.
|
||||
- Swapfile vergroot naar 16 GB.
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
hostnamectl
|
||||
free -h
|
||||
swapon --show
|
||||
df -h
|
||||
```
|
||||
|
||||
### Directorystructuur
|
||||
|
||||
Alle service-data staat onder:
|
||||
|
||||
```text
|
||||
/srv/scrum4me
|
||||
```
|
||||
|
||||
Structuur:
|
||||
|
||||
```text
|
||||
/srv/scrum4me/postgres database data
|
||||
/srv/scrum4me/repos GitHub clones
|
||||
/srv/scrum4me/worker-cache worker caches
|
||||
/srv/scrum4me/worker-logs worker logs
|
||||
/srv/scrum4me/worker-state worker state
|
||||
/srv/scrum4me/backups Postgres backups
|
||||
/srv/scrum4me/compose Docker Compose files
|
||||
/srv/scrum4me/caddy Caddy config/data
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
Docker Engine draait native op Ubuntu.
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
docker run hello-world
|
||||
docker compose version
|
||||
```
|
||||
|
||||
### Postgres
|
||||
|
||||
Postgres draait als Docker container:
|
||||
|
||||
```text
|
||||
container: scrum4me-postgres
|
||||
image: postgres:17
|
||||
```
|
||||
|
||||
Host mapping:
|
||||
|
||||
```text
|
||||
127.0.0.1:5432 -> postgres:5432
|
||||
```
|
||||
|
||||
Host-app gebruikt:
|
||||
|
||||
```env
|
||||
DATABASE_URL="postgresql://scrum4me:<password>@127.0.0.1:5432/scrum4me"
|
||||
DIRECT_URL="postgresql://scrum4me:<password>@127.0.0.1:5432/scrum4me"
|
||||
```
|
||||
|
||||
Containers gebruiken:
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
|
||||
DIRECT_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
|
||||
```
|
||||
|
||||
DB-test:
|
||||
|
||||
```bash
|
||||
docker exec -e PGPASSWORD="$DBPASS" scrum4me-postgres \
|
||||
psql -h 127.0.0.1 -U scrum4me -d scrum4me \
|
||||
-c "select current_user, current_database();"
|
||||
```
|
||||
|
||||
### Scrum4Me Web
|
||||
|
||||
Repo:
|
||||
|
||||
```text
|
||||
/srv/scrum4me/repos/Scrum4Me
|
||||
```
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
cd /srv/scrum4me/repos/Scrum4Me
|
||||
rm -rf .next
|
||||
npm run build
|
||||
```
|
||||
|
||||
Runtime:
|
||||
|
||||
```text
|
||||
systemd service: scrum4me-web
|
||||
```
|
||||
|
||||
Service startcommand:
|
||||
|
||||
```bash
|
||||
npm run start -- -H 0.0.0.0
|
||||
```
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
systemctl status scrum4me-web --no-pager
|
||||
curl -I http://127.0.0.1:3000/login
|
||||
```
|
||||
|
||||
### Caddy
|
||||
|
||||
Caddy draait als Docker container:
|
||||
|
||||
```text
|
||||
container: scrum4me-caddy
|
||||
```
|
||||
|
||||
Caddy reverse proxyt:
|
||||
|
||||
```text
|
||||
http://192.168.0.154 -> Caddy -> 172.18.0.1:3000 -> Scrum4Me web
|
||||
```
|
||||
|
||||
Caddyfile:
|
||||
|
||||
```caddyfile
|
||||
:80 {
|
||||
reverse_proxy 172.18.0.1:3000
|
||||
}
|
||||
```
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
curl -I http://192.168.0.154/login
|
||||
docker logs --tail=50 scrum4me-caddy
|
||||
```
|
||||
|
||||
### LAN Session Config
|
||||
|
||||
Omdat de server nu via HTTP op LAN draait, is secure session cookie tijdelijk uitgezet.
|
||||
|
||||
Env:
|
||||
|
||||
```env
|
||||
SESSION_COOKIE_SECURE="false"
|
||||
```
|
||||
|
||||
Code-aanpassing:
|
||||
|
||||
```ts
|
||||
secure: process.env.SESSION_COOKIE_SECURE === 'true',
|
||||
```
|
||||
|
||||
Later, bij domein + HTTPS:
|
||||
|
||||
```env
|
||||
SESSION_COOKIE_SECURE="true"
|
||||
```
|
||||
|
||||
Daarna:
|
||||
|
||||
```bash
|
||||
rm -rf .next
|
||||
npm run build
|
||||
sudo systemctl restart scrum4me-web
|
||||
```
|
||||
|
||||
### Migrations
|
||||
|
||||
De database is gemigreerd.
|
||||
|
||||
Belangrijke migration-notitie:
|
||||
|
||||
`20260506101436_restore_todos_table` kan op een bestaande DB falen met:
|
||||
|
||||
```text
|
||||
relation "todos" already exists
|
||||
```
|
||||
|
||||
Voor deze server is de juiste aanpak:
|
||||
|
||||
```bash
|
||||
npx prisma migrate resolve --applied 20260506101436_restore_todos_table
|
||||
npx prisma migrate deploy
|
||||
```
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
npx prisma migrate status
|
||||
docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me -c "\dt public.users"
|
||||
```
|
||||
|
||||
### Admin en Product
|
||||
|
||||
Admin user is aangemaakt via:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-admin.ts janpeter '<password>'
|
||||
```
|
||||
|
||||
Login werkt.
|
||||
|
||||
Product aanmaken werkt.
|
||||
|
||||
### Backups
|
||||
|
||||
Backup-script:
|
||||
|
||||
```text
|
||||
/srv/scrum4me/backup-postgres.sh
|
||||
```
|
||||
|
||||
Script:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
BACKUP_DIR="/srv/scrum4me/backups"
|
||||
STAMP="$(date +%Y%m%d-%H%M%S)"
|
||||
FILE="$BACKUP_DIR/scrum4me-$STAMP.sql.gz"
|
||||
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
docker exec scrum4me-postgres pg_dump -U scrum4me scrum4me | gzip > "$FILE"
|
||||
|
||||
find "$BACKUP_DIR" -type f -name 'scrum4me-*.sql.gz' -mtime +14 -delete
|
||||
|
||||
echo "backup written: $FILE"
|
||||
```
|
||||
|
||||
Test:
|
||||
|
||||
```bash
|
||||
/srv/scrum4me/backup-postgres.sh
|
||||
ls -lh /srv/scrum4me/backups
|
||||
```
|
||||
|
||||
Cron:
|
||||
|
||||
```cron
|
||||
15 3 * * * /srv/scrum4me/backup-postgres.sh >> /srv/scrum4me/backups/backup.log 2>&1
|
||||
```
|
||||
|
||||
## Worker-Idea Installatie
|
||||
|
||||
Worker compose-service:
|
||||
|
||||
```text
|
||||
worker-idea
|
||||
container: scrum4me-worker-idea
|
||||
health: http://127.0.0.1:18081/health
|
||||
```
|
||||
|
||||
Belangrijke env-waarden:
|
||||
|
||||
```env
|
||||
SCRUM4ME_BASE_URL=http://caddy
|
||||
SCRUM4ME_TOKEN=<raw Scrum4Me API token>
|
||||
|
||||
DATABASE_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
|
||||
DIRECT_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
|
||||
|
||||
GH_TOKEN=<GitHub token>
|
||||
GH_PRECLONE_REPOS=madhura68/Scrum4Me,madhura68/scrum4me-mcp,madhura68/scrum4me-docker
|
||||
|
||||
CLAUDE_CODE_OAUTH_TOKEN=<Claude Code OAuth token>
|
||||
```
|
||||
|
||||
Token-validatie:
|
||||
|
||||
```bash
|
||||
read -s -p "Scrum4Me token: " TOKEN; echo
|
||||
curl -i -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3000/api/products
|
||||
unset TOKEN
|
||||
```
|
||||
|
||||
Verwacht:
|
||||
|
||||
```text
|
||||
HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
Worker health:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:18081/health
|
||||
```
|
||||
|
||||
Gezonde idle-output bevat:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "idle",
|
||||
"heartbeatAgeSeconds": 1,
|
||||
"consecutiveFailures": 0
|
||||
}
|
||||
```
|
||||
|
||||
## Huidige Worker-Beperking
|
||||
|
||||
De Docker worker is gezond, maar Scrum4Me UI toont mogelijk nog:
|
||||
|
||||
```text
|
||||
geen Claude worker actief
|
||||
```
|
||||
|
||||
Oorzaak:
|
||||
|
||||
- De Docker health-server draait altijd.
|
||||
- De daemon-loop draait altijd.
|
||||
- Maar de DB-tabel `claude_workers` wordt nu alleen bijgewerkt door de MCP stdio-server.
|
||||
- Die MCP stdio-server start pas binnen een echte Claude/MCP job-run.
|
||||
- Bij een lege queue is de Docker worker dus idle en gezond, maar verschijnt hij niet als actieve worker in de UI.
|
||||
|
||||
Controle:
|
||||
|
||||
```bash
|
||||
docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me \
|
||||
-c "select t.id, t.label, w.id as worker_id, w.last_seen_at from api_tokens t left join claude_workers w on w.token_id=t.id order by t.created_at desc;"
|
||||
```
|
||||
|
||||
Gezonde Docker-worker maar lege presence:
|
||||
|
||||
```text
|
||||
label | worker_id | last_seen_at
|
||||
worker-idea | |
|
||||
```
|
||||
|
||||
## Worker Aanpassingsplan
|
||||
|
||||
### Doelrollen
|
||||
|
||||
```text
|
||||
worker-idea
|
||||
IDEA_GRILL
|
||||
IDEA_MAKE_PLAN
|
||||
PLAN_CHAT
|
||||
|
||||
worker-implementation
|
||||
TASK_IMPLEMENTATION
|
||||
SPRINT_IMPLEMENTATION
|
||||
later STORY_IMPLEMENTATION
|
||||
|
||||
worker-orchestrator
|
||||
PR_REVIEW
|
||||
CI_TRIAGE
|
||||
MERGE_CONFLICT_RESOLUTION
|
||||
REPAIR_FAILED_JOB
|
||||
CONTEXT_SUMMARY
|
||||
```
|
||||
|
||||
## Fase 1 — Presence Fix
|
||||
|
||||
### Probleem
|
||||
|
||||
Worker-health is nu container-lokaal, maar UI-presence is DB-gebaseerd.
|
||||
|
||||
Nu:
|
||||
|
||||
```text
|
||||
curl :18081/health -> online
|
||||
claude_workers -> leeg
|
||||
UI -> offline
|
||||
```
|
||||
|
||||
### Gewenst gedrag
|
||||
|
||||
Zolang de Docker daemon-loop draait, moet `claude_workers.last_seen_at` vers blijven, ook als de queue leeg is.
|
||||
|
||||
### Aanpassing
|
||||
|
||||
Verplaats worker-presence naar `scrum4me-docker/bin/run-one-job.ts` of naar een kleine runner-level heartbeat naast `run-agent.sh`.
|
||||
|
||||
Aanbevolen: in `run-one-job.ts`, direct na `getAuth()`:
|
||||
|
||||
```ts
|
||||
const { userId, tokenId } = await getAuth()
|
||||
await registerWorker({ userId, tokenId })
|
||||
const heartbeat = startHeartbeat({ userId, tokenId, intervalMs: 10_000 })
|
||||
```
|
||||
|
||||
In `finally`:
|
||||
|
||||
```ts
|
||||
heartbeat.stop()
|
||||
```
|
||||
|
||||
Niet unregisteren bij normale idle-exit. Anders gaat de UI-indicator flikkeren tussen iteraties.
|
||||
|
||||
### Acceptatie
|
||||
|
||||
Bij lege queue:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:18081/health
|
||||
```
|
||||
|
||||
toont:
|
||||
|
||||
```text
|
||||
status idle
|
||||
```
|
||||
|
||||
En:
|
||||
|
||||
```sql
|
||||
select token_id, last_seen_at, now() - last_seen_at from claude_workers;
|
||||
```
|
||||
|
||||
toont een recente `last_seen_at`.
|
||||
|
||||
## Fase 2 — Role-Aware Workers
|
||||
|
||||
### Probleem
|
||||
|
||||
De huidige worker claimt elke job die beschikbaar is. Daardoor kan `worker-idea` ook implementation jobs claimen.
|
||||
|
||||
### Nieuwe env
|
||||
|
||||
```env
|
||||
SCRUM4ME_WORKER_ROLE=idea
|
||||
```
|
||||
|
||||
Toegestane waarden:
|
||||
|
||||
```text
|
||||
idea
|
||||
implementation
|
||||
orchestrator
|
||||
```
|
||||
|
||||
### Claimfilter
|
||||
|
||||
`tryClaimJob` krijgt een role/capability-filter.
|
||||
|
||||
Mapping:
|
||||
|
||||
```text
|
||||
idea:
|
||||
IDEA_GRILL
|
||||
IDEA_MAKE_PLAN
|
||||
PLAN_CHAT
|
||||
|
||||
implementation:
|
||||
TASK_IMPLEMENTATION
|
||||
SPRINT_IMPLEMENTATION
|
||||
|
||||
orchestrator:
|
||||
PR_REVIEW
|
||||
CI_TRIAGE
|
||||
MERGE_CONFLICT_RESOLUTION
|
||||
REPAIR_FAILED_JOB
|
||||
CONTEXT_SUMMARY
|
||||
```
|
||||
|
||||
### Acceptatie
|
||||
|
||||
Test:
|
||||
|
||||
- Queue bevat één `IDEA_GRILL` en één `TASK_IMPLEMENTATION`.
|
||||
- Alleen `worker-idea` actief: claimt alleen `IDEA_GRILL`.
|
||||
- Alleen `worker-implementation` actief: claimt alleen `TASK_IMPLEMENTATION`.
|
||||
- Beide actief: ieder claimt eigen jobtype.
|
||||
|
||||
## Fase 3 — DB/UI Uitbreiding
|
||||
|
||||
Breid `claude_workers` uit met:
|
||||
|
||||
```text
|
||||
role
|
||||
worker_name
|
||||
container_name
|
||||
last_status
|
||||
last_job_id
|
||||
last_error
|
||||
```
|
||||
|
||||
UI toont dan:
|
||||
|
||||
```text
|
||||
Idea worker online / idle
|
||||
Implementation worker offline
|
||||
Orchestrator online / idle
|
||||
```
|
||||
|
||||
## Fase 4 — Orchestrator Jobs
|
||||
|
||||
Nieuwe job kinds:
|
||||
|
||||
```text
|
||||
PR_REVIEW
|
||||
CI_TRIAGE
|
||||
MERGE_CONFLICT_RESOLUTION
|
||||
REPAIR_FAILED_JOB
|
||||
CONTEXT_SUMMARY
|
||||
```
|
||||
|
||||
Orchestrator mag:
|
||||
|
||||
- PR's inspecteren.
|
||||
- CI-fouten samenvatten.
|
||||
- Merge conflicts analyseren.
|
||||
- Repair jobs aanmaken.
|
||||
- Context capsules schrijven.
|
||||
- Human escalation vragen.
|
||||
- Draft PR naar ready begeleiden.
|
||||
|
||||
Orchestrator mag niet:
|
||||
|
||||
- Vrij featurewerk implementeren.
|
||||
- Dezelfde branch tegelijk wijzigen als implementation-worker.
|
||||
- Auto-mergen zonder checks.
|
||||
- Secrets of tokens loggen.
|
||||
|
||||
## Fase 5 — Deployment
|
||||
|
||||
Na code-aanpassing:
|
||||
|
||||
```bash
|
||||
cd /srv/scrum4me/repos/scrum4me-docker
|
||||
git pull
|
||||
cd /srv/scrum4me/compose
|
||||
docker compose build worker-idea
|
||||
docker compose up -d --force-recreate worker-idea
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:18081/health
|
||||
docker logs -f scrum4me-worker-idea
|
||||
docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me \
|
||||
-c "select token_id, last_seen_at from claude_workers;"
|
||||
```
|
||||
|
||||
## Aanbevolen Volgorde Vanaf Nu
|
||||
|
||||
1. Test één `IDEA_GRILL` job met de huidige worker.
|
||||
2. Implementeer Fase 1: runner-level presence.
|
||||
3. Rebuild `worker-idea`.
|
||||
4. Verifieer UI online/idle bij lege queue.
|
||||
5. Implementeer Fase 2: role-aware claiming.
|
||||
6. Voeg `worker-implementation` toe.
|
||||
7. Voeg pas daarna `worker-orchestrator` toe.
|
||||
|
||||
Niet meteen drie workers starten zonder role-aware claimfilter.
|
||||
135
docs/Ideas/sprint-page-backlog-relationship-research.md
Normal file
135
docs/Ideas/sprint-page-backlog-relationship-research.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
title: "Advies — Product Backlog en Sprint-pagina workflow"
|
||||
status: draft
|
||||
audience: [product, ai-agent]
|
||||
language: nl
|
||||
last_updated: 2026-05-11
|
||||
---
|
||||
|
||||
# Advies — Product Backlog en Sprint-pagina workflow
|
||||
|
||||
## Aanleiding
|
||||
|
||||
Het bestaande plan `dit-verhaal-gaat-over-dazzling-mccarthy.md` beschrijft een nieuwe Product Backlog-workflow waarin sprint-membership via vinkjes wordt beheerd. De vraag is hoe de Sprint-pagina daarop moet aansluiten, met als doel om de huidige sprint verder samen te stellen.
|
||||
|
||||
## Korte conclusie
|
||||
|
||||
Maak de Product Backlog-pagina de brede plek voor backlog-refinement en sprint-scope selectie, en maak de Sprint-pagina de werkomgeving voor de huidige sprint: scope bijstellen, volgorde bepalen, taken uitwerken, assignees zetten, capaciteit bewaken en afronden.
|
||||
|
||||
De twee pagina's mogen dezelfde onderliggende membership-acties gebruiken, maar ze moeten niet dezelfde primaire UI dupliceren. De Product Backlog is de product-brede selectie- en overzichtslaag. De Sprint-pagina is de sprint-specifieke uitwerkingslaag.
|
||||
|
||||
## Verhouding tussen de pagina's
|
||||
|
||||
| Pagina | Primaire vraag | Scope | Hoofdhandeling |
|
||||
|---|---|---|---|
|
||||
| Product Backlog `/products/[id]` | Wat is waardevol, wat is klaar, wat hoort bij welke sprint? | Alle PBI's/stories van het product | Refinen, ordenen, nieuwe sprintdraft maken, sprint-membership bulk selecteren |
|
||||
| Sprint-pagina `/products/[id]/sprint/[sprintId]` | Hoe maken we deze sprint uitvoerbaar en af? | Een gekozen sprint | Sprint Backlog ordenen, stories aanvullen/verwijderen, taken maken, eigenaarschap/capaciteit/voortgang beheren |
|
||||
|
||||
## Aanbevolen workflow
|
||||
|
||||
1. Product Backlog zonder actieve sprint: klassieke refinement-view zonder vinkjes.
|
||||
2. Product Backlog met nieuwe sprintdraft: metadata invullen, PBI's/stories selecteren via vinkjes, sprint aanmaken.
|
||||
3. Product Backlog met actieve sprint: product-breed zien welke PBI's/stories in de sprint zitten en membership in batches aanpassen.
|
||||
4. Sprint-pagina: huidige sprint verder samenstellen en uitvoeren. Het middenpaneel is de waarheid voor de huidige Sprint Backlog. Het backlogpaneel is alleen toevoer/context.
|
||||
|
||||
## Consequenties voor de Sprint-pagina
|
||||
|
||||
Aanbevolen aanpassing:
|
||||
|
||||
- Header toont Sprint Goal, dates, status, switcher, scope-dirty teller en afronden-flow.
|
||||
- Linkerpaneel hernoemen van `Product Backlog` naar iets als `Aanvullen uit backlog`; standaard filter op eligible stories: `OPEN`, niet `DONE`, geen andere `OPEN` sprint.
|
||||
- Middenpaneel blijft `Sprint Backlog`: geselecteerde stories, sortering, assignee, task-progress, remove.
|
||||
- Rechterpaneel blijft `Taken`: taakdecompositie, taakvolgorde, status, implementatieplan.
|
||||
- Membership-mutaties op de Sprint-pagina gebruiken dezelfde serveractie als de Product Backlog: `commitSprintMembershipAction(activeSprintId, adds, removes)`.
|
||||
- Scopewijzigingen zijn pending/dirty tot `Scope opslaan (N)`. Story/task-field edits blijven direct opslaan.
|
||||
- Cross-sprint conflicts tonen als disabled story met tooltip. Server blijft autoritatief.
|
||||
- Na start van een sprint markeer je add/remove visueel als scopewijziging, omdat dat gevolgen heeft voor burndown/rapportage.
|
||||
|
||||
Wat je juist niet moet doen:
|
||||
|
||||
- Geen tweede volledige PBI-tri-state bulkselectie bouwen op de Sprint-pagina. Dat hoort op de Product Backlog.
|
||||
- Geen aparte sprint-membership semantiek naast het plan. `story.sprint_id` blijft unit-of-truth.
|
||||
- Geen nieuwe afrondactie. De bestaande `completeSprintAction` blijft de sprint-completion-flow.
|
||||
|
||||
## Andere methoden uit websearch
|
||||
|
||||
### 1. Scrum Guide: why / what / how
|
||||
|
||||
De Scrum Guide beschrijft Sprint Planning als drie onderwerpen: waarom is deze sprint waardevol, wat kan deze sprint gedaan worden, en hoe wordt het gekozen werk gedaan. De Sprint Backlog bestaat uit Sprint Goal, geselecteerde PBIs en een uitvoerbaar plan.
|
||||
|
||||
Impliceert voor Scrum4Me:
|
||||
|
||||
- Product Backlog-pagina: vooral `what`.
|
||||
- Sprint-pagina: vooral `how`, plus gecontroleerde bijstelling van `what`.
|
||||
|
||||
Bron: https://scrumguides.org/scrum-guide.html
|
||||
|
||||
### 2. Jira-methode: sprints plannen vanuit backlog, board voor active sprint
|
||||
|
||||
Jira plant sprints op het Backlog-scherm. De backlog toont werk gegroepeerd in backlog en sprints; items kunnen naar sprints worden gesleept. Na start verschijnt de sprint op het board. Jira waarschuwt ook dat add/remove in een actieve sprint scope change is.
|
||||
|
||||
Impliceert voor Scrum4Me:
|
||||
|
||||
- De richting van het plan is marktconform: sprint-samenstelling vanuit de backlog.
|
||||
- De Sprint-pagina mag scope aanpassen, maar moet dat als scopewijziging behandelen.
|
||||
|
||||
Bronnen:
|
||||
|
||||
- https://support.atlassian.com/jira-software-cloud/docs/use-your-scrum-backlog/
|
||||
- https://support.atlassian.com/jira-software-cloud/docs/enable-sprints/
|
||||
- https://support.atlassian.com/jira-software-cloud/docs/plan-a-sprint/
|
||||
|
||||
### 3. Azure Boards-methode: eerst items toewijzen, daarna capaciteit checken
|
||||
|
||||
Azure Boards beschrijft sprintplanning in twee delen: eerst backlog items selecteren, daarna bepalen hoe het team ontwikkelt/test, taken definiëren en capaciteit controleren. Azure toont geplande effort en capaciteit om onder- of overbelasting zichtbaar te maken.
|
||||
|
||||
Impliceert voor Scrum4Me:
|
||||
|
||||
- Voeg op de Sprint-pagina een lichte capacity/forecast-strip toe zodra story points, effort of taakminuten beschikbaar zijn.
|
||||
- Laat de Sprint-pagina na selectie vooral helpen met taakdecompositie en load balancing.
|
||||
|
||||
Bronnen:
|
||||
|
||||
- https://learn.microsoft.com/en-us/azure/devops/boards/sprints/assign-work-sprint
|
||||
- https://learn.microsoft.com/en-us/azure/devops/boards/sprints/adjust-work
|
||||
|
||||
### 4. Backlog refinement als aparte continue praktijk
|
||||
|
||||
Atlassian beschrijft refinement als doorlopend reviewen, rangschikken en verduidelijken van de Product Backlog zodat Sprint Planning soepeler loopt.
|
||||
|
||||
Impliceert voor Scrum4Me:
|
||||
|
||||
- Houd refinement-controls op de Product Backlog: PBI/story details, status, priority, split/merge later.
|
||||
- Maak de Sprint-pagina niet de primaire plek voor product-brede refinement.
|
||||
|
||||
Bron: https://www.atlassian.com/agile/scrum/backlog-refinement
|
||||
|
||||
### 5. Linear cycles / Scrumban-achtige methode
|
||||
|
||||
Linear cycles zijn time-boxed perioden met een vooraf bepaalde set werk, inclusief automatiseringen zoals rollover en auto-add van actieve issues. Dit is minder strikt Scrum, maar nuttig voor solo/kleine teams.
|
||||
|
||||
Impliceert voor Scrum4Me:
|
||||
|
||||
- Eventueel later: optionele automation "carry over unfinished stories to next sprint".
|
||||
- Niet als basis voor de huidige Scrum4Me-flow, omdat Scrum4Me al Sprint Goal, Sprint Backlog en completion-semantiek heeft.
|
||||
|
||||
Bron: https://linear.app/docs/use-cycles
|
||||
|
||||
## Aanbevolen ontwerpkeuze
|
||||
|
||||
Kies voor een hybride die dicht bij Scrum/Jira/Azure ligt:
|
||||
|
||||
- Product Backlog = refinement + sprint-scope bulkselectie.
|
||||
- Sprint-pagina = huidige sprint afmaken: ordenen, decomponeren, capaciteit en uitvoering.
|
||||
- Eén gedeelde membership-laag in code: dezelfde conflictregels, task cascade, statusmutaties en affected-id returns.
|
||||
|
||||
Dit houdt het mentale model simpel: je kunt overal zien wat in de sprint zit, maar elke pagina heeft een eigen reden om te bestaan.
|
||||
|
||||
## Implementatie-notities
|
||||
|
||||
1. Hergebruik `commitSprintMembershipAction` op de Sprint-pagina voor add/remove.
|
||||
2. Vervang directe `addStoryToSprintAction` / `removeStoryFromSprintAction` in `SprintBoardClient` geleidelijk door een pending scope-buffer, of laat ze intern dezelfde transactiesemantiek gebruiken als tijdelijke tussenstap.
|
||||
3. Fix bij die refactor ook task-cascade consistentie: remove moet `task.sprint_id = null` zetten voor taken onder verwijderde stories.
|
||||
4. Gebruik de nieuwe `cross-sprint-blocks` en `sprint-membership-summary` endpoints ook op de Sprint-pagina, maar gescoped op zichtbare PBI's.
|
||||
5. Voeg later capacity toe als aparte story, niet als voorwaarde voor de eerste workflow-migratie.
|
||||
|
||||
|
|
@ -73,7 +73,7 @@ Belangrijk maar niet-blokkerend voor v1.
|
|||
|
||||
### Backlog-index sync
|
||||
|
||||
[docs/backlog/index.md](../backlog/index.md) toont M10 (ST-1001 t/m 1008) en M11 (ST-1101 t/m 1108) als unchecked, terwijl ze allemaal gemerged zijn. Loop één keer door en zet `[x]`. Is een 5-min-job die de doc weer betrouwbaar maakt voor wie 'm leest.
|
||||
[docs/old/backlog/index.md](../old/backlog/index.md) toont M10 (ST-1001 t/m 1008) en M11 (ST-1101 t/m 1108) als unchecked, terwijl ze allemaal gemerged zijn. Loop één keer door en zet `[x]`. Is een 5-min-job die de doc weer betrouwbaar maakt voor wie 'm leest.
|
||||
|
||||
### Solo observaties (todo `cmohuu5h8`)
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ notes: |
|
|||
## 1. Context (this becomes the PBI description)
|
||||
|
||||
This PBI executes the docs-restructure plan
|
||||
([`docs/plans/docs-restructure-ai-lookup.md`](./docs-restructure-ai-lookup.md))
|
||||
([`docs/old/plans/docs-restructure-ai-lookup.md`](../old/plans/docs-restructure-ai-lookup.md))
|
||||
over eight phases, mapped here as eight stories with three to eight tasks
|
||||
each. The goal is to cut the documentation surface an AI agent has to read
|
||||
to find the right reference, without breaking existing workflows.
|
||||
|
|
@ -81,7 +81,7 @@ in parallel with Stories 3–5 if you want.
|
|||
### Where to look first
|
||||
|
||||
- This file (the PBI context block above).
|
||||
- [`docs/plans/docs-restructure-ai-lookup.md`](./docs-restructure-ai-lookup.md)
|
||||
- [`docs/old/plans/docs-restructure-ai-lookup.md`](../old/plans/docs-restructure-ai-lookup.md)
|
||||
— the full plan, especially §3 (Goals), §4 (Target structure), §6
|
||||
(Front-matter spec), §8 (Phased migration).
|
||||
- [`docs/adr/README.md`](../adr/README.md) — when writing an ADR in
|
||||
|
|
@ -143,7 +143,7 @@ pbi:
|
|||
- One commit per logical layer (`docs(<story-slug>):` prefix).
|
||||
- No pushes without user approval.
|
||||
- Update every internal link in the same commit as a rename.
|
||||
Read docs/plans/docs-restructure-ai-lookup.md §3, §4, §6, §8 first.
|
||||
Read docs/old/plans/docs-restructure-ai-lookup.md §3, §4, §6, §8 first.
|
||||
priority: 2
|
||||
|
||||
stories:
|
||||
|
|
@ -337,7 +337,7 @@ pbi:
|
|||
acceptance_criteria: |
|
||||
- docs/ root contains only INDEX.md and (later) glossary.md.
|
||||
- All existing docs moved into the right folder per
|
||||
docs/plans/docs-restructure-ai-lookup.md §4.
|
||||
docs/old/plans/docs-restructure-ai-lookup.md §4.
|
||||
- Internal links updated in the same commit as each move.
|
||||
- `npm run docs:index` shows docs grouped correctly.
|
||||
priority: 2
|
||||
|
|
|
|||
|
|
@ -7,6 +7,9 @@ last_updated: 2026-05-03
|
|||
applies_to: [SCRUM4ME]
|
||||
story_id: cmoq2qoik0001qa175iynfnaa
|
||||
pbi_id: cmoq2q50s0000qa174rmrjove
|
||||
archived: true
|
||||
archived_reason: niet-uitgevoerd, uit standaard sessiecontext gehouden
|
||||
archived_at: 2026-05-11
|
||||
---
|
||||
|
||||
# Landing v2 — lokaal & veilig + architectuurdiagram
|
||||
|
|
|
|||
|
|
@ -8,6 +8,9 @@ applies_to: [SCRUM4ME]
|
|||
story_id: cmot8226500017h174z5qpphx
|
||||
story_code: ST-1224
|
||||
pbi_id: cmoq2q50s0000qa174rmrjove
|
||||
archived: true
|
||||
archived_reason: niet-uitgevoerd, uit standaard sessiecontext gehouden
|
||||
archived_at: 2026-05-11
|
||||
---
|
||||
|
||||
# Landing v3 — van idee tot pull request
|
||||
|
|
|
|||
|
|
@ -163,6 +163,6 @@ push direct naar main.
|
|||
|
||||
- Workflow: `.github/workflows/ci.yml`
|
||||
- Vercel-config: `vercel.json`
|
||||
- Plan: `docs/plans/auto-pr-deploy-sync.md` Deel A
|
||||
- Plan: `docs/old/plans/auto-pr-deploy-sync.md` Deel A
|
||||
- Branch- & commit-strategie: [`docs/runbooks/branch-and-commit.md`](./branch-and-commit.md)
|
||||
- Auto-PR-flow (toekomstig): `docs/plans/auto-pr-deploy-sync.md` Deel B
|
||||
- Auto-PR-flow (toekomstig): `docs/old/plans/auto-pr-deploy-sync.md` Deel B
|
||||
|
|
|
|||
|
|
@ -189,6 +189,6 @@ Volledige resolver-uitleg + override-cascade staat in
|
|||
- Status-data-cleanup: `app/api/cron/cleanup-agent-artifacts/route.ts`
|
||||
- KPI-aggregatie: `lib/insights/agent-throughput.ts` (terminal_7d
|
||||
inclusief SKIPPED)
|
||||
- Gerelateerd plan: `docs/plans/auto-pr-deploy-sync.md` Deel D
|
||||
- Gerelateerd plan: `docs/old/plans/auto-pr-deploy-sync.md` Deel D
|
||||
- PBI-67 resolver: `scrum4me-mcp/src/lib/job-config.ts` + `lib/job-config.ts`
|
||||
(Sync-tab toont per-Story job-status incl. SKIPPED)
|
||||
|
|
|
|||
|
|
@ -25,6 +25,7 @@ const EXCLUDE_PATTERNS = [
|
|||
/^docs\/adr\/README\.md$/,
|
||||
/\/_[^/]+\.md$/,
|
||||
/^docs\/INDEX\.md$/,
|
||||
/^docs\/old\//,
|
||||
];
|
||||
|
||||
async function walk(dir) {
|
||||
|
|
@ -121,6 +122,7 @@ async function main() {
|
|||
|
||||
const content = await readFile(full, 'utf8');
|
||||
const { data, body } = parseFrontMatter(content);
|
||||
if (data.archived === 'true') continue;
|
||||
|
||||
const title =
|
||||
data.title || extractFirstH1(body) || basename(full, '.md');
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue