docs: AI-optimized docs restructure (Phases 1–8) (#61)
* docs(dialog-pattern): add generic entity-dialog spec Introduceert docs/patterns/dialog.md als bron-of-truth voor elke create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende dataobject. Bevat 14 secties: uitgangspunten, stack, component- architectuur, layout, validatie, drielaagse demo-policy, submission, dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit profile-template, out-of-scope, en een verificatie-checklist. Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel zodat Claude (en mensen) de spec verplicht raadplegen voor elke nieuwe dialog. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(dialog-pattern): convert task spec + add pbi/story entity-profiles Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document bevat nu alleen Task-specifieke velden, URL-pattern, status-veld, server actions, triggers en bewuste out-of-scope-keuzes. Voegt twee nieuwe entity-profielen toe voor bestaande dialogen: - docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij, PbiStatusSelect, geen delete in v1) - docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met status/priority badges, inline activity-log, demo-readonly-fallback, inline-delete-confirm i.p.v. AlertDialog) Beide profielen documenteren expliciet de "Bekende gaps t.o.v. generieke spec" zodat opvolgende PR's de afwijkingen kunnen rechtzetten of bewust kunnen accorderen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Added pdevelopment docs * docs(plans): add docs-restructure plan for AI-optimized lookup Audit of existing 39 doc files (~10.700 lines) and a phased restructure proposal aimed at minimising the tokens an AI agent has to read to find the right reference. Captures resolved decisions on language (English), ADR template (Nygard default with MADR escape-hatch), index generator (node script), and folder taxonomy. Proposal status — fase 1 to follow. * docs(adr): add ADR scaffolding (templates, README, meta-ADR) Set up docs/adr/ as the canonical home for architecture decisions: - templates/nygard.md — default four-section format (Status, Context, Decision, Consequences) for one-way-door decisions. - templates/madr.md — MADR v4 with YAML front-matter and explicit Considered Options for decisions where rejected alternatives matter. - README.md — naming convention (NNNN-kebab-case), template-selection guidance (Nygard default; MADR for auth, queue mechanics, agent integration), status lifecycle, and ADR roster. - 0000-record-architecture-decisions.md — meta-ADR establishing the practice itself, in Nygard format. Backfilling existing implicit decisions (base-ui-over-radix, float sort_order, demo-user three-layer policy, etc.) is fase 6 of the docs-restructure plan. * feat(docs): add docs index generator + initial INDEX.md scripts/generate-docs-index.mjs walks docs/**/*.md, parses YAML front-matter (or first H1 fallback) and a Nygard-style ## Status section, then writes docs/INDEX.md with grouped tables for ADRs, Specs, Plans (with archive subsection), Patterns, and Other. Pure Node 20 (no external deps); idempotent — running it twice produces byte-identical output. Excludes adr/templates/, the ADR README, INDEX.md itself, and any *_*.md sidecar file. Wire-up: - package.json: docs:index → node scripts/generate-docs-index.mjs Initial run indexed 35 docs across the existing structure; the generated INDEX.md is committed so the table is reviewable in the PR before hooking generation into a pre-commit step. * chore: ignore Obsidian vault and personal sidecar files Add .obsidian/ (Obsidian vault config) and _*.md (personal sidecar notes) to .gitignore so the docs/ tree can serve as canonical source of truth while still being usable as an Obsidian vault for personal authoring. The docs index generator already excludes the same _*.md pattern from INDEX.md. * docs(plans): add PBI bulk-create spec for docs-restructure Machine-parseable spec for an executor that calls the scrum4me MCP (create_pbi → create_story → create_task) to seed the docs-restructure work into the DB. - Section 1 (Context) is the PBI description; serves as task-context via mcp__scrum4me__get_claude_context. - Section 2 lists the 6 resolved decisions (English, MD3+styling merged, solo-paneel merged, .Plans archived, Nygard ADR default, node index script). - Section 3 records what already shipped on this branch so the executor doesn't duplicate the ADR scaffolding or index generator. - Section 4 carries the structured YAML graph: 1 PBI, 8 stories (one per phase), 39 tasks. product_id is REPLACE_ME — fill before running. - YAML validated with PyYAML; field schema sanity-checked. * docs(junk-cleanup): remove stub patterns/test.md * docs(junk-cleanup): archive .Plans/ to docs/plans/archive/ * docs(front-matter): add YAML front-matter to docs/ root * docs(front-matter): add YAML front-matter to patterns/ * docs(front-matter): add YAML front-matter to plans + agent files * docs(index): regenerate INDEX.md after front-matter pass * docs(naming): drop scrum4me- prefix from doc filenames * docs(naming): lowercase API.md and MD3 filenames * docs(naming): rename plan file to kebab-case ASCII * docs(naming): rename middleware.md to proxy.md (next 16) * docs(naming): polish CLAUDE.md doc-index after renames * docs(taxonomy): scaffold topical folders under docs/ * docs(taxonomy): move spec files into docs/specs/ * docs(taxonomy): move design/api/qa/backlog/assets into folders * docs(taxonomy): move agent-instruction-audit into decisions/ * docs(split): break architecture.md into 6 topical files * docs(split): merge solo-paneel-spec into specs/functional.md * docs(split): merge md3-color-scheme into design/styling * docs(trim): extract branch/commit rules into runbook * docs(trim): extract MCP integration into runbook * docs(adr): add 0001-base-ui-over-radix * docs(adr): add 0002-float-sort-order * docs(adr): add 0003-one-branch-per-milestone * docs(adr): add 0004-status-enum-mapping * docs(adr): add 0005-iron-session-over-nextauth * docs(adr): add 0006-demo-user-three-layer-policy * docs(adr): add 0007-claude-question-channel-design * docs(adr): add 0008-agent-instructions-in-claude-md + update README index * docs(index): regenerate after ADR 0001-0008 * docs(glossary): add docs/glossary.md * chore(docs): regenerate INDEX.md in pre-commit hook * docs(readme): link INDEX + glossary + agent instructions * feat(docs): add doc-link checker script * chore(docs): wire docs:check-links and docs npm scripts * ci(docs): block merge on broken doc links * docs(links): fix broken cross-references after restructure --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser
GitHub
parent
289bcf9bf0
commit
7e45bbdbc0
81 changed files with 12364 additions and 3154 deletions
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "M10 — Password-loze inlog via QR-pairing"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [M10]
|
||||
---
|
||||
|
||||
# M10 — Password-loze inlog via QR-pairing
|
||||
|
||||
Inloggen op een (publieke) desktop zonder wachtwoord: desktop toont QR, telefoon (al-ingelogd) scant en bevestigt expliciet, desktop is binnen 1–2 s ingelogd. Bouwt voort op M8 LISTEN/NOTIFY-infra met eigen channel `scrum4me_pairing`.
|
||||
|
|
@ -7,8 +16,8 @@ Inloggen op een (publieke) desktop zonder wachtwoord: desktop toont QR, telefoon
|
|||
- `desktopToken` reist alleen via HttpOnly cookie `s4m_pair` met `Path=/api/auth/pair`, `Max-Age=120`, `SameSite=Lax`
|
||||
- Twee gescheiden hashes in DB scheiden mobiel-bewijs (`secret_hash`) van desktop-bewijs (`desktop_token_hash`)
|
||||
|
||||
Backlog-entries: zie [backlog.md § M10](../backlog.md#m10-password-loze-inlog-via-qr-pairing).
|
||||
Functional spec: zie [functional.md § F-01b](../functional.md#f-01b-inloggen-via-mobiel-qr-pairing).
|
||||
Backlog-entries: zie [backlog.md § M10](../backlog/index.md#m10-password-loze-inlog-via-qr-pairing).
|
||||
Functional spec: zie [functional.md § F-01b](../specs/functional.md#f-01b-inloggen-via-mobiel-qr-pairing).
|
||||
|
||||
**Implementatie-volgorde** (commit-strategy uit CLAUDE.md):
|
||||
|
||||
|
|
@ -28,7 +37,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
**Bestanden**
|
||||
- `prisma/schema.prisma` — nieuw model `LoginPairing` + back-relation op `User`
|
||||
- `prisma/migrations/<timestamp>_add_login_pairing/migration.sql` — model + trigger
|
||||
- `vendor/scrum4me`-submodule in repo `scrum4me-mcp` — schema-sync ná merge
|
||||
- `vendor/scrum4me`-submodule in repo `mcp` — schema-sync ná merge
|
||||
|
||||
**Stappen**
|
||||
|
||||
|
|
@ -84,7 +93,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
- `desktop_ip` houdt op 45 tekens om IPv6 te accommoderen (`xxxx:xxxx:…:255.255.255.255`).
|
||||
- Geen index op `user_id` nodig voor v1 — er is geen lookup-pad "geef alle pairings van user X" (komt pas bij remote-revoke in M+1).
|
||||
- Trigger emit ook bij DELETE niet nodig — pairings worden niet gedelete'd, ze gaan naar `consumed`/`cancelled`.
|
||||
- `vendor/scrum4me`-submodule in scrum4me-mcp moet ná merge op `main` direct gesynced worden, anders breekt de wekelijkse drift-check (`trig_015FFUnxjz9WMuhhWNGBQKFD`). Dit was ook een aandachtspunt bij ST-901.
|
||||
- `vendor/scrum4me`-submodule in mcp moet ná merge op `main` direct gesynced worden, anders breekt de wekelijkse drift-check (`trig_015FFUnxjz9WMuhhWNGBQKFD`). Dit was ook een aandachtspunt bij ST-901.
|
||||
|
||||
**Verificatie**
|
||||
- `npx prisma migrate dev` slaagt
|
||||
|
|
@ -767,7 +776,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
<QrLoginButton />
|
||||
```
|
||||
|
||||
MD3-tokens uit `docs/styling.md`; geen willekeurige Tailwind-kleuren.
|
||||
MD3-tokens uit `docs/design/styling.md`; geen willekeurige Tailwind-kleuren.
|
||||
|
||||
4. **A11y**: QR-component krijgt `aria-label="QR-code voor mobiel inloggen"` en de URL wordt visueel als kopieer-bare tekst onder de QR getoond zodat screenreaders en gebruikers met cameraproblemen de URL handmatig kunnen openen.
|
||||
|
||||
|
|
@ -788,7 +797,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
## ST-1008 — Documentatie + acceptatietest
|
||||
|
||||
**Bestanden**
|
||||
- `docs/api.md` — drie nieuwe endpoints
|
||||
- `docs/api/rest-contract.md` — drie nieuwe endpoints
|
||||
- `docs/architecture.md` — sectie "QR-pairing flow" + threat-model
|
||||
- `docs/patterns/qr-login.md` — nieuw pattern-doc
|
||||
- `CLAUDE.md` — verwijzing naar het pattern-doc in de patterns-tabel
|
||||
|
|
@ -796,7 +805,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
|
||||
**Stappen**
|
||||
|
||||
1. **`docs/api.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
|
||||
1. **`docs/api/rest-contract.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
|
||||
|
||||
2. **`docs/architecture.md`** — sectie *"QR-pairing flow"* met:
|
||||
- Sequence-diagram (mermaid of ASCII analoog aan M8)
|
||||
|
|
@ -826,19 +835,19 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
|
|||
7. **Secret niet in access logs** — controleer Vercel runtime-logs (via `mcp__a1fa0fcf-…__get_runtime_logs`) en lokale dev-logs; zoek op de secret-string en op `s=`-substrings; verwacht: 0 hits
|
||||
|
||||
**Aandachtspunten**
|
||||
- Zorg dat de runtime-logs MCP-controle in `docs/test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
|
||||
- Zorg dat de runtime-logs MCP-controle in `docs/qa/api-test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
|
||||
- `docs/patterns/qr-login.md` mag refereren naar bestaande pattern-docs (iron-session, route-handler) zonder ze te dupliceren.
|
||||
|
||||
**Verificatie**
|
||||
- `npm run lint && npx tsc --noEmit && npm test && npm run build` groen
|
||||
- Alle zeven scenario's handmatig groen, beschreven in een test-rapport-sectie
|
||||
- `vendor/scrum4me`-submodule in scrum4me-mcp gesynced ná schema-merge
|
||||
- `vendor/scrum4me`-submodule in mcp gesynced ná schema-merge
|
||||
|
||||
---
|
||||
|
||||
## Branch- en commit-strategie
|
||||
|
||||
Per [CLAUDE.md → Branch & PR Strategy](../../CLAUDE.md#branch--pr-strategy-strict--kostenbeheersing): **één branch voor de hele milestone**, PR pas na handmatige acceptatie door de gebruiker. Reden: elke push triggert een Vercel preview-build, en op het Hobby-account zijn die schaars.
|
||||
Per [Branch & PR Strategy](../runbooks/branch-and-commit.md): **één branch voor de hele milestone**, PR pas na handmatige acceptatie door de gebruiker. Reden: elke push triggert een Vercel preview-build, en op het Hobby-account zijn die schaars.
|
||||
|
||||
**Branch:** `feat/M10-qr-login` — afgesplitst van `main` na merge van de planning-PR (#11). Alle ST-1001..ST-1008-werk landt op deze branch.
|
||||
|
||||
|
|
@ -866,7 +875,7 @@ docs(ST-1008): add qr-login pattern doc
|
|||
|
||||
**Pre-merge gates** (uit CLAUDE.md DoD):
|
||||
- `npm run lint && npm test && npm run build` groen op CI
|
||||
- Schema-wijziging in ST-1001 → wekelijkse drift-check `trig_015FFUnxjz9WMuhhWNGBQKFD` mag niet rood staan; `vendor/scrum4me`-submodule in scrum4me-mcp meebewegen na merge
|
||||
- Schema-wijziging in ST-1001 → wekelijkse drift-check `trig_015FFUnxjz9WMuhhWNGBQKFD` mag niet rood staan; `vendor/scrum4me`-submodule in mcp meebewegen na merge
|
||||
|
||||
**Wanneer dit aanpassen:** zodra het Vercel-account naar Pro gaat — zie CLAUDE.md.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,19 @@
|
|||
---
|
||||
title: "M11 — Claude vraagt, gebruiker antwoordt"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [M11]
|
||||
---
|
||||
|
||||
# M11 — Claude vraagt, gebruiker antwoordt
|
||||
|
||||
Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scrum4Me-gebruiker. Claude schrijft een vraag naar `claude_questions` als hij vastloopt op een keuze; een Postgres-trigger emit op het bestaande `scrum4me_changes`-kanaal; de app toont een notificatie-badge; iedereen met product-toegang kan antwoorden; Claude leest het antwoord (sync via polling of in latere sessie via `get_question_answer`) en gaat door.
|
||||
|
||||
Eerste concrete uitwerking van strategische **richting B** (verdiepen van de unieke AI-driven dev-flow).
|
||||
|
||||
Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruiker-antwoordt) (op te leveren in ST-1108).
|
||||
Backlog-entries: zie [backlog.md § M11](../backlog/index.md#m11-claude-vraagt-gebruiker-antwoordt) (op te leveren in ST-1108).
|
||||
|
||||
**Beveiligingsuitgangspunten:**
|
||||
- Atomic answer via `updateMany WHERE status='open'` — concurrent dubbele submit kan niet
|
||||
|
|
@ -25,7 +34,7 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
**Bestanden**
|
||||
- `prisma/schema.prisma` — model `ClaudeQuestion` + relations op `User`/`Story`/`Task`/`Product`
|
||||
- `prisma/migrations/<ts>_add_claude_questions/migration.sql` — table-DDL + trigger
|
||||
- `vendor/scrum4me`-submodule in `scrum4me-mcp` — schema-sync ná merge
|
||||
- `vendor/scrum4me`-submodule in `mcp` — schema-sync ná merge
|
||||
|
||||
**Stappen**
|
||||
|
||||
|
|
@ -104,16 +113,16 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
|
||||
---
|
||||
|
||||
## ST-1102 — MCP-tools (in `scrum4me-mcp`-repo)
|
||||
## ST-1102 — MCP-tools (in `mcp`-repo)
|
||||
|
||||
**Bestanden**
|
||||
- `scrum4me-mcp/src/tools/ask-user-question.ts` — nieuw
|
||||
- `scrum4me-mcp/src/tools/get-question-answer.ts` — nieuw
|
||||
- `scrum4me-mcp/src/tools/list-open-questions.ts` — nieuw
|
||||
- `scrum4me-mcp/src/tools/cancel-question.ts` — nieuw
|
||||
- `scrum4me-mcp/src/index.ts` — register de vier tools
|
||||
- `scrum4me-mcp/scripts/smoke-test.ts` — uitbreiden met question-roundtrip
|
||||
- `scrum4me-mcp/README.md` — tool-tabel uitbreiden
|
||||
- `mcp/src/tools/ask-user-question.ts` — nieuw
|
||||
- `mcp/src/tools/get-question-answer.ts` — nieuw
|
||||
- `mcp/src/tools/list-open-questions.ts` — nieuw
|
||||
- `mcp/src/tools/cancel-question.ts` — nieuw
|
||||
- `mcp/src/index.ts` — register de vier tools
|
||||
- `mcp/scripts/smoke-test.ts` — uitbreiden met question-roundtrip
|
||||
- `mcp/README.md` — tool-tabel uitbreiden
|
||||
|
||||
**Stappen**
|
||||
|
||||
|
|
@ -153,7 +162,7 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
- MCP Inspector toont 4 nieuwe tools (totaal 13)
|
||||
- Smoke-test groen: ask + answer roundtrip binnen 5s
|
||||
- Demo-token op `ask_user_question` of `cancel_question` geeft `PERMISSION_DENIED`
|
||||
- `tsc --noEmit` clean op `scrum4me-mcp`
|
||||
- `tsc --noEmit` clean op `mcp`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -279,7 +288,7 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
|
||||
**Aandachtspunten**
|
||||
- Bell-icon en avatar moeten visueel balanceren — hoogte/padding gelijktrekken
|
||||
- MD3-tokens uit `docs/styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
|
||||
- MD3-tokens uit `docs/design/styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
|
||||
- Optimistic-answer in store: voor het Server Action-resultaat zet item op pending; bij error rollback met sonner-error-toast
|
||||
- Sheet-content blijft open zodat de user meerdere vragen achter elkaar kan beantwoorden (zelfde patroon als ST-358 openstaande-stories-sheet)
|
||||
- ARIA: bell-icon heeft `aria-label="Notificaties — N open vragen"`, badge `role="status"`
|
||||
|
|
@ -369,16 +378,16 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
## ST-1108 — Documentatie + acceptatietest
|
||||
|
||||
**Bestanden**
|
||||
- `docs/api.md` — secties "SSE — Notifications" + "Cron — Expire questions"
|
||||
- `docs/api/rest-contract.md` — secties "SSE — Notifications" + "Cron — Expire questions"
|
||||
- `docs/architecture.md` — sectie "Vraag-antwoord-kanaal" met sequence-diagram
|
||||
- `docs/patterns/claude-question-channel.md` — herbruikbaar pattern-doc
|
||||
- `docs/backlog.md` — M11-tabel-rij + M11-sectie
|
||||
- `docs/backlog/index.md` — M11-tabel-rij + M11-sectie
|
||||
- `prisma/seed-data/parse-backlog.ts` — `M11: 'ACTIVE'`, `M10: 'COMPLETED'`, `M3.5: 'COMPLETED'`
|
||||
- `CLAUDE.md` — pattern-doc verwijzing in Implementatiepatronen-tabel
|
||||
|
||||
**Stappen**
|
||||
|
||||
1. Backlog-tabel-rij + M11-sectie in `docs/backlog.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
|
||||
1. Backlog-tabel-rij + M11-sectie in `docs/backlog/index.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
|
||||
|
||||
2. `docs/architecture.md` § "Vraag-antwoord-kanaal":
|
||||
- Mermaid sequence-diagram: Claude → MCP → DB → trigger → SSE → user → Server Action → DB → trigger → polling-tool
|
||||
|
|
@ -406,21 +415,21 @@ Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruik
|
|||
- Backlog-parser-self-test: `npx tsx prisma/seed-data/parse-backlog.ts` toont M11 met `priority=4 sprint=ACTIVE`
|
||||
- 6/6 acceptatie-scenario's groen
|
||||
- `npm run lint && npx tsc --noEmit && npm test && npm run build` clean
|
||||
- `vendor/scrum4me`-submodule sync in scrum4me-mcp na merge
|
||||
- `vendor/scrum4me`-submodule sync in mcp na merge
|
||||
|
||||
---
|
||||
|
||||
## Branch- en commit-strategie
|
||||
|
||||
Per [CLAUDE.md → Branch & PR Strategy](../../CLAUDE.md#branch--pr-strategy-strict--kostenbeheersing):
|
||||
Per [Branch & PR Strategy](../runbooks/branch-and-commit.md):
|
||||
- **Eén branch op Scrum4Me**: `feat/M11-claude-questions` afgesplitst van `main` ná M10-merge
|
||||
- **Aparte branch op scrum4me-mcp**: `feat/M11-question-tools`
|
||||
- **Aparte branch op mcp**: `feat/M11-question-tools`
|
||||
- Commits chronologisch per stap met ST-code in titel:
|
||||
|
||||
```
|
||||
chore(M11): swap demo-active sprint from M10 to M11
|
||||
feat(ST-1101): add ClaudeQuestion model + notify_question_change trigger
|
||||
feat(ST-1102): add 4 MCP question tools (in scrum4me-mcp)
|
||||
feat(ST-1102): add 4 MCP question tools (in mcp)
|
||||
feat(ST-1103): add answerQuestion server action
|
||||
feat(ST-1104): add /api/realtime/notifications user-scoped SSE
|
||||
feat(ST-1104): filter entity='question' from solo-realtime stream
|
||||
|
|
|
|||
|
|
@ -1,8 +1,17 @@
|
|||
---
|
||||
title: "M9 — Actief Product Backlog"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [M9]
|
||||
---
|
||||
|
||||
# M9 — Actief Product Backlog
|
||||
|
||||
Eén "actief Product Backlog" per gebruiker, persistent op `User.active_product_id`. NavBar wordt: Producten | Product Backlog | Sprint | Solo | Todo's. Zonder actief PB zijn Backlog/Sprint/Solo disabled. Sprint is alleen klikbaar als er een sprint met status `ACTIVE` bestaat. Vervangt de bestaande `last_product`-cookieflow.
|
||||
|
||||
Backlog-entries: zie [backlog.md § M9](../backlog.md#m9-actief-product-backlog).
|
||||
Backlog-entries: zie [backlog.md § M9](../backlog/index.md#m9-actief-product-backlog).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -20,7 +29,7 @@ Backlog-entries: zie [backlog.md § M9](../backlog.md#m9-actief-product-backlog)
|
|||
3. `npx prisma migrate dev --name add_user_active_product_id`.
|
||||
|
||||
**Aandachtspunten**
|
||||
- `vendor/scrum4me`-submodule in repo `scrum4me-mcp` heeft hetzelfde schema. Na merge moet daar `prisma generate && tsc --noEmit` slagen, anders breekt de wekelijkse drift-check (`trig_015FFUnxjz9WMuhhWNGBQKFD`).
|
||||
- `vendor/scrum4me`-submodule in repo `mcp` heeft hetzelfde schema. Na merge moet daar `prisma generate && tsc --noEmit` slagen, anders breekt de wekelijkse drift-check (`trig_015FFUnxjz9WMuhhWNGBQKFD`).
|
||||
- Geen seed-wijziging nodig — `null` is correcte initiële staat.
|
||||
|
||||
**Verificatie**
|
||||
|
|
|
|||
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "ST-1109 — PBI krijgt een status (Ready / Blocked / Done)"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [ST-1109]
|
||||
---
|
||||
|
||||
# Plan — ST-1109 · PBI krijgt een status (Ready / Blocked / Done)
|
||||
|
||||
> Spiegel van het goedgekeurde plan dat tijdens de sessie is opgesteld in
|
||||
|
|
|
|||
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "ST-1110 — Demo gebruiker read-only"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [ST-1110]
|
||||
---
|
||||
|
||||
# Plan: ST-1110 — Demo gebruiker read-only
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "ST-1111 — Voer uit-knop met Claude Code job queue"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [ST-1111]
|
||||
---
|
||||
|
||||
# ST-1111 — 'Voer uit'-knop met Claude Code job queue
|
||||
|
||||
**Story:** Als developer wil ik op het solo-scherm per task een 'Voer uit'-knop, zodat ik mijn lokale Claude Code-sessie kan inschakelen om de taak uit te voeren.
|
||||
|
|
@ -14,7 +23,7 @@
|
|||
| ST-1111.2 API: ClaudeJob status mappers | `a1b1f69` |
|
||||
| ST-1111.3 Server actions: enqueue + cancel | `9d9fb4b` |
|
||||
| ST-1111.4 SSE: ClaudeJob events op solo-stream + initial state | `ece0aa9` |
|
||||
| ST-1111.5 MCP-tools (scrum4me-mcp repo — aparte PR) | — |
|
||||
| ST-1111.5 MCP-tools (mcp repo — aparte PR) | — |
|
||||
| ST-1111.6 UI: 'Voer uit' + cancel in TaskDetailDialog | `b9c65eb` |
|
||||
| ST-1111.7 UI: status-pill op SoloTaskCard | `dace427` |
|
||||
| ST-1111.8 Tests: mappers + actions | `2c2a246` |
|
||||
|
|
@ -41,7 +50,7 @@ Omdat `claude_jobs` geen row-trigger heeft (zoals `tasks` en `stories`), stuurt
|
|||
await prisma.$executeRaw`SELECT pg_notify('scrum4me_changes', ${JSON.stringify(payload)}::text)`
|
||||
```
|
||||
|
||||
Voordeel: expliciete controle over het payload-shape (met `type` i.p.v. `entity`). Nadeel: MCP-tools in de `scrum4me-mcp`-repo moeten hun eigen NOTIFY-aanroep hebben bij `update_job_status`.
|
||||
Voordeel: expliciete controle over het payload-shape (met `type` i.p.v. `entity`). Nadeel: MCP-tools in de `mcp`-repo moeten hun eigen NOTIFY-aanroep hebben bij `update_job_status`.
|
||||
|
||||
### SSE-routing
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "ST-1114 — Copilot reviews op dashboard"
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [ST-1114]
|
||||
---
|
||||
|
||||
# Plan — ST-1114 · Copilot reviews op dashboard
|
||||
|
||||
## Context
|
||||
|
|
|
|||
150
docs/plans/archive/2026-04-27-claude-md-workflow-update.md
Normal file
150
docs/plans/archive/2026-04-27-claude-md-workflow-update.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
title: "CLAUDE.md workflow-update na M7 + ST-509/511/512/513"
|
||||
status: done
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [M7, ST-509, ST-511, ST-512, ST-513]
|
||||
---
|
||||
|
||||
# Plan: CLAUDE.md workflow-update na M7 + ST-509/511/512/513
|
||||
|
||||
## Aanleiding
|
||||
|
||||
`CLAUDE.md` is voor het laatst groot bijgewerkt op 2026-04-25 (`docs/decisions/agent-instructions-history.md`). Sindsdien is er substantieel werk geland dat de workflow raakt:
|
||||
|
||||
- **ST-511** entity codes (Product/PBI/Story) — branch- en commit-conventies hangen er nu aan vast
|
||||
- **ST-513** API hardening — `400` (malformed JSON) vs `422` (zod-validatie), lowercase status-enums op API-grens, `StoryLog.metadata` JSONB
|
||||
- **PR #2** review-saga (8 testbestanden faalden bij contract-flip) — duidelijk leerpunt: testpariteit hoort bij contract-wijziging
|
||||
- **M7 MCP-server** — Claude Code praat nu native met Scrum4Me via `mcp__scrum4me__*` tools en de prompt `implement_next_story`. De huidige 7-stap "vraag-de-gebruiker"-loop in CLAUDE.md is daarmee gedateerd
|
||||
- **lib/code-server.ts** vs **lib/code.ts** — split is nodig om client-bundle vrij te houden van `pg`. Als gotcha noemenswaard
|
||||
- **Schema-drift cron** (`trig_015FFUnxjz9WMuhhWNGBQKFD`) — wekelijkse remote agent — agents moeten weten wat ze met zijn rapport doen
|
||||
|
||||
Doel: CLAUDE.md weerspiegelt de werkelijke 2026-04-27 workflow zonder dat het een changelog wordt.
|
||||
|
||||
## Scope — wat we wél en niet aanpassen
|
||||
|
||||
**Wel** (in `CLAUDE.md`):
|
||||
1. Workflow-sectie — MCP-first met expliciete fallback
|
||||
2. Conventies — uitbreiden met status-enums, foutcodes, test-pariteit, entity codes in commits
|
||||
3. Implementatiepatronen — rij voor `lib/task-status.ts` en `lib/code-server.ts`-boundary toevoegen
|
||||
4. Nieuwe sectie "MCP-integratie" — wat staat er, hoe te gebruiken, link naar mcp repo
|
||||
5. Definition of Done — markeer expliciet als MVP-scope; M7 is post-MVP en heeft eigen acceptatie
|
||||
|
||||
**Niet**:
|
||||
- Geen changelog of historiek in CLAUDE.md zelf — dat hoort in `docs/decisions/agent-instructions-history.md` (separate update)
|
||||
- Geen volledige herschrijving — bestaande structuur blijft (Wat is Scrum4Me, Spec-tabel, Stack, Conventies, Commit Strategy, etc.)
|
||||
- Geen wijziging in `AGENTS.md` (Codex) — die heeft geen MCP, mag los blijven
|
||||
- Geen wijziging in functional-spec/architecture/styling docs — die zijn al actueel
|
||||
|
||||
## Concrete edits in `CLAUDE.md`
|
||||
|
||||
### 1. Sectie "Specificatiedocumenten" — uitbreiden
|
||||
|
||||
Voeg toe onder de bestaande tabel:
|
||||
|
||||
| Document | Gebruik voor |
|
||||
|---|---|
|
||||
| `https://github.com/madhura68/scrum4me-mcp` | MCP-server repo: tools, prompts, schema-sync workflow |
|
||||
|
||||
(`docs/api/rest-contract.md` staat er al — laten staan.)
|
||||
|
||||
### 2. Sectie "Waar te beginnen" — herschrijven
|
||||
|
||||
Vervang de 7-stap manual loop door een dual-track:
|
||||
|
||||
**Track A — via Claude Code MCP (aanbevolen)**:
|
||||
```
|
||||
1. Roep `mcp__scrum4me__implement_next_story` aan met product_id
|
||||
(of `list_products` als je het id niet weet)
|
||||
2. De prompt orkestreert: get_claude_context → log_implementation
|
||||
→ per task in_progress/done → log_test_result → log_commit
|
||||
3. Bouw de tasks in volgorde van `sort_order`
|
||||
4. Test: `npm run lint && npm test && npm run build`
|
||||
5. Commit per laag (zie Commit Strategy)
|
||||
```
|
||||
|
||||
**Track B — manueel (Codex of zonder MCP)**:
|
||||
- Lees task in `docs/backlog/index.md`
|
||||
- Volg verder de bestaande 7-stappen-loop
|
||||
|
||||
### 3. Sectie "Implementatiepatronen" — uitbreiden
|
||||
|
||||
Twee rijen toevoegen aan de patronen-tabel:
|
||||
|
||||
| Patroon | Bestand |
|
||||
|---|---|
|
||||
| Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
|
||||
| Client/server module-boundary | regel: `*-server.ts` bevat DB-calls, `*.ts` is pure helpers — nooit `import { ... } from 'lib/foo-server'` in een client component |
|
||||
|
||||
### 4. Sectie "Conventies" — vier regels toevoegen
|
||||
|
||||
Voeg toe aan de bestaande lijst:
|
||||
|
||||
- **Entity codes**: gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
|
||||
- **Status-enums op API**: lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie via `lib/task-status.ts`-mappers — nooit ad-hoc lowercase elders
|
||||
- **Foutcodes API**: `400` alleen voor malformed JSON-body (parse-fout); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteren in `docs/api/rest-contract.md`
|
||||
- **Tests volgen contract**: bij API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` bijgewerkt worden — een falende test op review betekent niet dat de tests "stuk zijn" maar dat de wijziging onvolledig is
|
||||
|
||||
### 5. Nieuwe sectie "MCP-integratie" — toevoegen vóór "Definition of Done"
|
||||
|
||||
Korte sectie (~15 regels):
|
||||
|
||||
```markdown
|
||||
## MCP-integratie
|
||||
|
||||
Scrum4Me heeft een eigen MCP-server (repo: `madhura68/scrum4me-mcp`)
|
||||
die deze API exposed als native tools voor Claude Code.
|
||||
|
||||
### Tools beschikbaar in Claude Code
|
||||
- `mcp__scrum4me__health` — service + DB ping
|
||||
- `mcp__scrum4me__list_products` — producten waar je toegang tot hebt
|
||||
- `mcp__scrum4me__get_claude_context` — bundled product/sprint/story/todos
|
||||
- `mcp__scrum4me__update_task_status`, `_update_task_plan`
|
||||
- `mcp__scrum4me__log_implementation`, `_log_test_result`, `_log_commit`
|
||||
- `mcp__scrum4me__create_todo`
|
||||
|
||||
### Prompt
|
||||
- `implement_next_story` (arg: `product_id`) — end-to-end workflow
|
||||
|
||||
### Schema-drift bewaking
|
||||
Wekelijks (maandag 08:00 Amsterdam) draait een remote agent
|
||||
(`trig_015FFUnxjz9WMuhhWNGBQKFD`) die `vendor/scrum4me` syncet en
|
||||
`prisma:generate + typecheck` uitvoert in mcp. Als die agent
|
||||
een drift-rapport opent, hoort dat **vóór** een Scrum4Me-PR met
|
||||
schema-wijziging gemerged kan worden — zodat de MCP-server niet
|
||||
stilletjes breekt op runtime.
|
||||
```
|
||||
|
||||
### 6. Sectie "Definition of Done" — kop verduidelijken
|
||||
|
||||
Wijzig `## Definition of Done` → `## Definition of Done (MVP)` en voeg eronder een korte zin toe: *"M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog/index.md`."*
|
||||
|
||||
## Bijwerken van auditdoc
|
||||
|
||||
Voeg een sectie aan `docs/decisions/agent-instructions-history.md` toe (datum: 2026-04-27) met:
|
||||
|
||||
- Aanleiding: ST-509/511/512/513 + M7 + PR #2 review-saga
|
||||
- Gecontroleerde wijzigingen: zelfde tabel-stijl als 2026-04-25
|
||||
- Nieuwe regels: status-enums op API-grens, error-code split 400/422, test-pariteit bij contract-wijziging, client/server module-boundary
|
||||
- Verwijzing naar mcp repo en schema-drift cron
|
||||
|
||||
## Volgorde van uitvoering
|
||||
|
||||
1. **Edits in `CLAUDE.md`** — alle 6 secties hierboven, in volgorde
|
||||
2. **Edits in `docs/decisions/agent-instructions-history.md`** — nieuwe sectie 2026-04-27
|
||||
3. **`npm run lint`** — sanity check
|
||||
4. **Commit als één logische change** — `docs(workflow): align CLAUDE.md with M7 and post-PR-#2 contract`
|
||||
5. **PR openen** — review-bare scope, deploys triggeren maar zijn docs-only
|
||||
|
||||
## Wat het NIET oplost
|
||||
|
||||
- `AGENTS.md` (Codex) blijft achter; los aan te pakken indien gewenst
|
||||
- Eventuele drift in `docs/specs/functional.md` rond status-enums — niet onderzocht; te volgen bij volgende audit
|
||||
- Geen check of de losse pattern-files in `docs/patterns/` nog kloppen — ook volgende audit
|
||||
|
||||
## Geschatte size
|
||||
|
||||
- ~80 regels toegevoegd/gewijzigd in `CLAUDE.md`
|
||||
- ~30 regels nieuw in `docs/decisions/agent-instructions-history.md`
|
||||
- 1 commit, 1 PR
|
||||
111
docs/plans/archive/2026-04-27-insert-milestone-tool.md
Normal file
111
docs/plans/archive/2026-04-27-insert-milestone-tool.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
title: "Herbruikbaar scripts/insert-milestone.ts"
|
||||
status: done
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: []
|
||||
---
|
||||
|
||||
# Plan: herbruikbaar `scripts/insert-milestone.ts`
|
||||
|
||||
## Doel
|
||||
|
||||
Eén commando dat een specifieke milestone (PBI + stories + tasks) uit de backlog leest en idempotent toevoegt aan de DB, zónder bestaande data te raken. Voor M8 nu, en voor M9..M∞ later.
|
||||
|
||||
## Bron-keuze: backlog ipv plan-bestand
|
||||
|
||||
Twee bronnen denkbaar:
|
||||
- **`.Plans/<datum>-<slug>.md`** — freeform plan-tekst, niet gestructureerd, niet gecommit
|
||||
- **`docs/backlog/index.md`** — al strict gestructureerd, gecommit, single source of truth voor alle bestaande seed-pipelines
|
||||
|
||||
Voorstel: het script leest de **backlog**. Workflow blijft natuurlijk:
|
||||
|
||||
1. Plan schrijven naar `.Plans/<naam>.md` (lokaal, draft)
|
||||
2. Milestone-sectie + stories formaliseren in `docs/backlog/index.md` (PR)
|
||||
3. Na merge: `npm run db:insert-milestone -- M8 [--product SCRUM4ME]`
|
||||
|
||||
Eén canonical bron, geen ambiguïteit, en de bestaande parser doet 90% van het werk al.
|
||||
|
||||
## Wijzigingen
|
||||
|
||||
### 1. `prisma/seed-data/parse-backlog.ts` — tolerant maken
|
||||
|
||||
Huidige parser kent alleen M0..M6 in `MILESTONE_PRIORITY/_GOAL/_SPRINT_STATUS` + asserts ≥8 milestones / ≥60 stories. M7 en M8 worden nu stilletjes overgeslagen.
|
||||
|
||||
Concrete edits:
|
||||
- Voeg `M7` en `M8` toe aan de drie maps (M7: priority 4, sprint COMPLETED, goal "MCP-server voor Claude Code"; M8: priority 4, sprint COMPLETED, goal "Realtime updates voor Solo Paneel")
|
||||
- Voor onbekende sleutels: fallback naar `priority: 4`, `sprint_status: 'COMPLETED'`, `goal: <header-title>`. Dat maakt M9..M∞ vanzelf bruikbaar zonder code-wijziging
|
||||
- Verwijder de strikte filter `KNOWN_KEYS.includes(...)` of verleg naar een "alle-M[\d.]+ headers" check
|
||||
- Voeg optionele `loadBacklog(repoRoot, { strict?: boolean })` toe. `strict: true` (default) behoudt de bestaande "≥8 milestones, ≥60 stories" asserts (zodat de seed niet stilletjes anders gedraagt). Insert-milestone roept met `strict: false`
|
||||
|
||||
### 2. `scripts/insert-milestone.ts` (nieuw, ~90 regels)
|
||||
|
||||
```
|
||||
Usage: tsx scripts/insert-milestone.ts <milestone-key> [--product <code>] [--dry-run]
|
||||
Default product code: SCRUM4ME
|
||||
```
|
||||
|
||||
Logica:
|
||||
1. Parse args; valideer dat milestone-key matcht `^M[\d.]+$`
|
||||
2. `loadBacklog(repoRoot, { strict: false })`
|
||||
3. Zoek milestone op `key`; faal helder met "milestone <key> not found in docs/backlog/index.md" als ie er niet in staat
|
||||
4. Lookup product via `code` (default `SCRUM4ME`); faal als niet gevonden
|
||||
5. Upsert PBI:
|
||||
- `where: { product_id_code: { product_id, code: milestone.key } }`
|
||||
- sort_order = `(max(sort_order) van bestaande PBIs in product) + 1` als nieuw, anders ongemoeid
|
||||
6. Voor elke story:
|
||||
- Upsert Story op `(product_id, code = story.ref)`
|
||||
- status = `'DONE'` of `'OPEN'` zoals gemarkeerd in markdown
|
||||
- sort_order, priority en pbi_id correct ingesteld
|
||||
7. Voor elke task: bulk insert **alleen** als de story op dit moment 0 tasks heeft (idempotent — herhaling dupliceert niets)
|
||||
8. Print samenvatting: `M8: PBI created, 6 stories upserted (1 created, 5 unchanged), 6 tasks created`
|
||||
9. `--dry-run`: alle DB-calls overslaan, alleen wat het zou doen printen
|
||||
|
||||
Edge cases:
|
||||
- Story-code conflict tussen producten: schema heeft `@@unique([product_id, code])` op Story dus dit is per-product safe
|
||||
- Tasks zonder `code` veld in DB (klopt — code wordt afgeleid van story.code + index in get_claude_context)
|
||||
- Demo-product: script accepteert `--product DEMO` o.i.d. — niet hardcoded SCRUM4ME
|
||||
|
||||
### 3. `package.json` script
|
||||
|
||||
```json
|
||||
"db:insert-milestone": "tsx scripts/insert-milestone.ts"
|
||||
```
|
||||
|
||||
### 4. Verificatie na implementatie
|
||||
|
||||
- Dry-run eerst: `npm run db:insert-milestone -- M8 --dry-run`
|
||||
- Daarna echt: `npm run db:insert-milestone -- M8`
|
||||
- In Prisma Studio of via SQL: zie M8 PBI, 6 stories, 6 tasks onder SCRUM4ME-product
|
||||
- Tweede run: `npm run db:insert-milestone -- M8` → "0 created, 6 unchanged" — geen duplicaten
|
||||
- Niet-bestaande key: `npm run db:insert-milestone -- M99` → "milestone M99 not found"
|
||||
- Bestaande seed-flow blijft werken: `prisma db seed` met `strict: true` faalt nog steeds bij format-drift in de backlog
|
||||
|
||||
## Branch- en PR-strategie
|
||||
|
||||
`scripts/insert-milestone.ts` is orthogonaal aan ST-801. Twee keuzes:
|
||||
|
||||
- **A. Eigen mini-branch + PR** — `tooling/insert-milestone-script`, ~95 regels code, makkelijk reviewbaar, gemerged voordat M8 verder gaat. Daarna gebruiken om M8 in DB te zetten en met de implementatie door.
|
||||
- **B. Aan ST-801 plakken** — voegt scope toe aan een PR die al code ↔ infra-overschrijdend is (migratie + tools).
|
||||
|
||||
Voorgestelde keuze: **A**. De tool is breder bruikbaar dan M8 alleen.
|
||||
|
||||
## Volgorde
|
||||
|
||||
1. Switch naar `main` (ST-801 blijft op zijn eigen branch staan)
|
||||
2. Branch `tooling/insert-milestone-script`
|
||||
3. Edit `parse-backlog.ts` (M7/M8 maps + tolerant + strict-mode option)
|
||||
4. Schrijf `scripts/insert-milestone.ts`
|
||||
5. Voeg `db:insert-milestone` toe aan `package.json`
|
||||
6. Lokaal testen met M8 (dry-run + echt + tweede run)
|
||||
7. Commit, push, PR
|
||||
8. Na merge: tool gebruiken om M8 in DB te krijgen, daarna ST-802 oppakken op feat/ST-801-branch
|
||||
|
||||
## Geschatte size
|
||||
|
||||
- ~10 regels parser-edit
|
||||
- ~95 regels nieuw script
|
||||
- ~1 regel package.json
|
||||
- ~25 regels test/usage doc in script-comment
|
||||
- 1 commit, 1 PR
|
||||
195
docs/plans/archive/2026-04-27-m8-realtime-solo.md
Normal file
195
docs/plans/archive/2026-04-27-m8-realtime-solo.md
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
---
|
||||
title: "Realtime updates voor Solo Paneel (M8)"
|
||||
status: done
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: [M8]
|
||||
---
|
||||
|
||||
# Plan: Realtime updates voor Solo Paneel (M8)
|
||||
|
||||
## Aanleiding
|
||||
|
||||
Wanneer Lars in zijn Solo Paneel werkt en parallel Claude Code (via MCP) of Codex aan dezelfde sprint sleutelt, ziet hij de gevolgen pas na een refresh. We willen DB-wijzigingen op `tasks`/`stories` van zijn actieve sprint live in beeld zien. Vraag van de gebruiker: "open een websocket".
|
||||
|
||||
## Transport-keuze — niet écht een WebSocket
|
||||
|
||||
Vercel-deploys ondersteunen geen stateful native WebSockets in serverless of Edge functions. Drie reële opties:
|
||||
|
||||
| Optie | Werkt op Vercel | Externe dienst | Latency | Complexiteit |
|
||||
|---|---|---|---|---|
|
||||
| **A. SSE + Postgres LISTEN/NOTIFY** | ✅ (Node runtime, streaming response) | nee | <100ms na DB-write | gemiddeld |
|
||||
| B. SSE + polling 2–3s | ✅ | nee | 1–3s | laag |
|
||||
| C. Pusher/Ably (echte WS) | ✅ | ja (gratis tier) | <50ms | laag, maar elke schrijver moet publishen |
|
||||
|
||||
**Voorgestelde keuze: A — SSE met Postgres LISTEN/NOTIFY.**
|
||||
|
||||
Reden:
|
||||
- Eén bron van waarheid: de DB. Web-mutations, REST-API én MCP schrijven allemaal naar Postgres; een trigger NOTIFY't onafhankelijk van de schrijver. Geen coördinatie nodig met mcp.
|
||||
- Geen externe dienst, geen extra dep, geen kosten erbij.
|
||||
- Neon ondersteunt LISTEN/NOTIFY op directe verbindingen. `DIRECT_URL` is al geconfigureerd.
|
||||
- Naar de client toe: éénrichtingsverkeer — server pusht events, client doet mutaties via bestaande Server Actions/REST. SSE volstaat dus; we hoeven geen full-duplex.
|
||||
- Voor de gebruiker is het verschil onmerkbaar: realtime updates komen binnen, browsers ondersteunen `EventSource` native.
|
||||
|
||||
We kiezen B (polling) niet omdat het meer DB-load geeft en je Pusher-achtige latency niet haalt. We kiezen C niet vanwege coördinatieoverhead met de MCP-server (extra publish-step in mcp).
|
||||
|
||||
## Architectuur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Postgres (Neon) │
|
||||
│ ┌────────────────────────┐ │
|
||||
│ │ TRIGGER on tasks │──► pg_notify('scrum4me_solo', payload_json) │
|
||||
│ │ TRIGGER on stories │ │
|
||||
│ └────────────────────────┘ │
|
||||
└──────────────┬──────────────────────────────────────────────────────────┘
|
||||
│ LISTEN scrum4me_solo
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Next.js Node.js runtime route: /api/realtime/solo │
|
||||
│ - auth via iron-session cookie │
|
||||
│ - opent dedicated pg client (DIRECT_URL), LISTEN scrum4me_solo │
|
||||
│ - filtert events: alleen tasks/stories in actieve sprint van een │
|
||||
│ product waar user lid/eigenaar is, EN (assignee_id == user OR │
|
||||
│ onbeklemtoonde unassigned-story-list) │
|
||||
│ - stuurt SSE: data: {type, entity, id, fields} \n\n │
|
||||
│ - heartbeat \n\n elke 25s │
|
||||
│ - sluit zelf na 4 min (Vercel maxDuration safety); client reconnect │
|
||||
└──────────────┬──────────────────────────────────────────────────────────┘
|
||||
│ EventSource('/api/realtime/solo?product_id=...')
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Browser — Solo Paneel │
|
||||
│ - useSoloRealtime(productId) hook │
|
||||
│ - reconnect met exponential backoff (max 30s) │
|
||||
│ - Page Visibility API: close on hidden, reopen on visible │
|
||||
│ - dispatcht naar solo-store: applyTaskUpdate, applyTaskCreate, │
|
||||
│ applyTaskDelete, applyStoryUpdate (assignee/title/status) │
|
||||
│ - reconcile-policy: skip update als optimistic in-flight is voor die │
|
||||
│ task; anders server wint │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Filtering — wie krijgt welke events?
|
||||
|
||||
De trigger NOTIFY't elke task/story-mutatie globaal. De SSE-handler is verantwoordelijk voor toegangs- en relevantie-filtering:
|
||||
|
||||
1. **Toegang**: alleen events waarvan de gerelateerde `story.product_id` in `productAccessFilter(userId)` zit.
|
||||
2. **Sprint-scope**: alleen events binnen de actieve sprint van het product dat in de query-parameter zit.
|
||||
3. **Persoonlijke relevantie**: tasks waar `story.assignee_id == userId` (jouw kolommen), plus stories met `assignee_id == null` (de "claim me" lijst).
|
||||
|
||||
Per event extra DB-roundtrip om dit te checken zou duur zijn. Twee oplossingen, bij voorkeur (b):
|
||||
|
||||
(a) Triggerpayload bevat `product_id`, `sprint_id`, `assignee_id` zodat de handler in-memory kan filteren — geen extra DB-call.
|
||||
|
||||
(b) Cache in handler: bij connect resolveert de handler `userId → activeSprintId, productId, assignedStoryIds`. Bij elke notify checkt het de payload tegen die set; bij story-create/assignee-change herwoordt het de set on demand.
|
||||
|
||||
Strategie: combineer (a) trigger zet `product_id` en `assignee_id` in de payload + (b) handler cacht `(activeSprintId, productId, accessibleProducts)` voor de connectie-duur.
|
||||
|
||||
## Concrete implementatie — stories
|
||||
|
||||
### ST-801 Postgres LISTEN/NOTIFY-infrastructuur
|
||||
- Migration `prisma/migrations/<ts>_add_solo_realtime_triggers/migration.sql`:
|
||||
- `CREATE OR REPLACE FUNCTION notify_solo_change() RETURNS TRIGGER ...` — bouwt JSON met `op` (`INSERT`/`UPDATE`/`DELETE`), `entity` (`task`/`story`), `id`, `product_id`, `sprint_id`, `assignee_id`, `fields` (alleen gewijzigde kolommen bij UPDATE)
|
||||
- Triggers `AFTER INSERT OR UPDATE OR DELETE ON tasks`, idem op `stories`
|
||||
- Pas `prisma migrate deploy` toe (idempotent, geen schema-wijziging dus geen TS-impact)
|
||||
- Done when: `psql $DIRECT_URL -c "LISTEN scrum4me_solo;"` toont een payload bij UI-mutatie
|
||||
|
||||
### ST-802 SSE-route `/api/realtime/solo`
|
||||
- Bestand `app/api/realtime/solo/route.ts`, `runtime: 'nodejs'`, `maxDuration: 300`
|
||||
- Gebruikt `pg.Client` (niet de Prisma adapter — directe `LISTEN`-verbinding)
|
||||
- Auth via iron-session, 401 zonder cookie
|
||||
- Query-parameter `product_id`, 403 zonder access
|
||||
- Resolveert active sprint id eenmalig; cachet die in connection-scope
|
||||
- `ReadableStream` met heartbeat-interval 25s, hard close na 240s
|
||||
- Filter per event op `product_id == requested && (assignee_id == userId || (entity == 'story' && assignee_id == null))`
|
||||
- Logged via `console.error` bij pg-disconnect
|
||||
- Done when: handmatig met `curl -N` op localhost krijg je events binnen 1s na een UI-mutatie
|
||||
|
||||
### ST-803 Client hook `useSoloRealtime(productId)`
|
||||
- `lib/realtime/use-solo-realtime.ts` (client-only)
|
||||
- Opent `EventSource('/api/realtime/solo?product_id=' + productId)`
|
||||
- Reconnect: exponential backoff start 1s → 30s, reset op succesvolle connect
|
||||
- Page Visibility: `document.visibilityState === 'hidden'` → close; bij visible → reopen
|
||||
- Cleanup op unmount
|
||||
- Dispatcht events naar solo-store via nieuwe acties (zie ST-804)
|
||||
- Done when: tab wisselen sluit/opent connectie zichtbaar in DevTools Network
|
||||
|
||||
### ST-804 Solo-store realtime-acties
|
||||
- Uitbreiden `stores/solo-store.ts`:
|
||||
- `applyTaskUpdate(taskId, fields)` — merge in tasks-record; skip als `pendingOps[taskId]` set is
|
||||
- `applyTaskCreate(task)` — alleen als de task in de eigen kolommen hoort (assignee_id == userId)
|
||||
- `applyTaskDelete(taskId)`
|
||||
- `applyStoryAssignment(storyId, assigneeId)` — re-fetch unassigned-list (kleine GET) of ontvang als deel van payload
|
||||
- `markPending(taskId)`/`clearPending(taskId)` — optimistic-flow markeert mutaties die we zelf doen, zodat we de echo van onze eigen NOTIFY niet dubbel verwerken
|
||||
- Done when: unit-test op solo-store met simulated events laat juiste state zien
|
||||
|
||||
### ST-805 Wire-up in SoloBoard
|
||||
- `components/solo/solo-board.tsx`: roep `useSoloRealtime(productId)` aan na `useEffect`-init van tasks
|
||||
- Klein "live" / "verbinden..." status-indicator (status uit hook): groene stip / pulserende grijze stip
|
||||
- Toast bij langer dan 5s disconnected
|
||||
- Done when: open Solo paneel in twee tabs, mutate task in tab A, zie status flippen in tab B binnen 1–2s zonder refresh
|
||||
|
||||
### ST-806 Documentatie + acceptatietest
|
||||
- Update `docs/architecture.md`: nieuwe sectie "Realtime updates" met diagram en filtering-regels
|
||||
- Update `CLAUDE.md`: vermelding dat Solo Paneel realtime is + dat MCP-writes vanzelf doorkomen
|
||||
- Update `docs/api/rest-contract.md`: korte note over `/api/realtime/solo` (Bearer auth, SSE format)
|
||||
- E2E-acceptatie: lijst van scenario's (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap) handmatig getest
|
||||
- Done when: scenario's lopen door zonder onverwachte gedragingen
|
||||
|
||||
## Backlog-edits
|
||||
|
||||
In `docs/backlog/index.md`:
|
||||
|
||||
1. **Milestone-overzicht** — rij toevoegen onder M7:
|
||||
```
|
||||
| M8: Realtime Solo Paneel | Live updates voor stories/tasks via SSE+LISTEN/NOTIFY | ST-801 – ST-806 |
|
||||
```
|
||||
|
||||
2. **Sectie M8** toevoegen na de M7-sectie, met de zes stories hierboven (ST-801..ST-806) inclusief "Done when"-criteria. Allemaal `[ ]` (nog niet gestart).
|
||||
|
||||
## Wijzigingen elders
|
||||
|
||||
- `.env.example` blijft ongewijzigd (DIRECT_URL stond er al)
|
||||
- `docs/architecture.md` — sectie "Realtime updates" met diagram en regel "alle UPDATE-triggers zitten op tasks/stories; nieuwe entiteiten erbij vragen om uitbreiding van de trigger-functie"
|
||||
- Geen wijziging in `lib/code.ts` of `lib/code-server.ts` — dit is server-only realtime
|
||||
- Schema-drift agent in mcp pikt de migratie automatisch op (geen Prisma-modelwijziging maar wel een nieuwe migratie); typecheck blijft groen omdat we geen Prisma Client-wijziging hebben
|
||||
|
||||
## Risico's en mitigaties
|
||||
|
||||
| Risico | Mitigatie |
|
||||
|---|---|
|
||||
| Vercel sluit Node-route na maxDuration | Hard-close server-side bij 240s + automatische client-reconnect; gebruiker merkt dit niet |
|
||||
| Echo van eigen optimistic mutation | `markPending`/`clearPending` in solo-store; skip als `pendingOps[taskId]` set is |
|
||||
| Connection leaks (open `pg.Client`'s) | `req.signal.addEventListener('abort')` cleanup; bij Edge cold-start sluit Vercel zelf |
|
||||
| Trigger overhead op writes | Triggers zijn lichtgewicht (één pg_notify call); meet bij rollout |
|
||||
| Oude pg_notify payloads >8kb | Zorg dat we alleen primitives (id, status, sort_order, etc.) sturen — geen description/implementation_plan in de payload, daar is een refetch voor |
|
||||
| Test-DB heeft geen triggers | Migratie automatisch toegepast in CI (Prisma migrate deploy); bestaande tests blijven groen |
|
||||
| MCP-server schema-sync detecteert migratie als drift | False alarm — wekelijkse cron rapporteert "schema-prisma diff", maar typecheck blijft groen omdat het alleen migratie-SQL is. Beoordeel handmatig bij rapport |
|
||||
|
||||
## Wat dit NIET oplost
|
||||
|
||||
- Realtime in Sprint Backlog of Product Backlog — alleen Solo Paneel
|
||||
- Conflict-merge bij gelijktijdige updates van twee gebruikers (last-write-wins blijft)
|
||||
- Mobile pagina (out of scope desktop-first MVP)
|
||||
- Audit-trail van wie wat wanneer veranderde (bestaat al via StoryLog)
|
||||
|
||||
## Volgorde van uitvoering
|
||||
|
||||
1. Branch `feat/m8-realtime-solo` van main
|
||||
2. ST-801 (migratie + trigger) — commit, lokaal verifiëren met `psql LISTEN`
|
||||
3. ST-802 (SSE-route) — commit, `curl -N` lokaal testen tegen lokale UI-mutatie
|
||||
4. ST-803 (client hook) — commit
|
||||
5. ST-804 (store-uitbreiding) — commit, met unit-test
|
||||
6. ST-805 (wire-up + UI-indicator) — commit
|
||||
7. ST-806 (docs + acceptatie) — commit
|
||||
8. PR openen — Vercel preview-deploy laat realtime werken op preview-DB (mits trigger via `migrate deploy` mee)
|
||||
9. Na review: merge
|
||||
|
||||
## Geschatte size
|
||||
|
||||
- ~6 stories, ~12–18 commits
|
||||
- 1 migratie, 1 nieuwe route, 1 nieuwe hook, kleine store-uitbreiding, UI-indicator
|
||||
- ~400 regels code + ~80 regels docs
|
||||
- 1 PR
|
||||
499
docs/plans/docs-restructure-ai-lookup.md
Normal file
499
docs/plans/docs-restructure-ai-lookup.md
Normal file
|
|
@ -0,0 +1,499 @@
|
|||
---
|
||||
title: Docs-restructuur — geoptimaliseerd voor AI-lookup
|
||||
status: proposal
|
||||
audience: maintainer, ai-agent
|
||||
language: nl
|
||||
last_updated: 2026-05-02
|
||||
related:
|
||||
- CLAUDE.md
|
||||
- AGENTS.md
|
||||
- README.md
|
||||
- docs/decisions/agent-instructions-history.md
|
||||
---
|
||||
|
||||
# Plan — Docs-restructuur voor AI-lookup
|
||||
|
||||
> Doel van dit plan: de huidige documentatie- en instructielaag van Scrum4Me omzetten naar een structuur die een AI-agent (Claude Code, Codex, een MCP-worker) in zo min mogelijk tokens en tool-calls het juiste document laat vinden, lezen en toepassen — zonder dat de mens-leesbaarheid eronder lijdt.
|
||||
|
||||
Dit is een **proposal**, niet een afgerond ontwerp. Lees het, markeer wat je niet wil, en ik werk het uit naar een uitvoerbaar migratieplan met file-per-file diff.
|
||||
|
||||
---
|
||||
|
||||
## 1. Waarom dit plan
|
||||
|
||||
Een AI-agent doet voor élke beslissing typisch dit:
|
||||
|
||||
1. Leest `CLAUDE.md` (of `AGENTS.md`) volledig in context.
|
||||
2. Scant `docs/` met `ls`/`grep`/`glob` om relevante bestanden te kiezen.
|
||||
3. Leest één of meerdere docs volledig — vaak meer dan nodig, omdat doc-grenzen vaag zijn.
|
||||
4. Vindt cross-refs (`zie docs/X#Y`) en herhaalt stap 3.
|
||||
|
||||
Elke stap kost tokens en latency. Als de bestandsboom, naamgeving of inhoud onduidelijk is, leest de agent te veel of het verkeerde — en maakt vervolgens beslissingen op verouderde of irrelevante informatie.
|
||||
|
||||
**Concrete kosten in deze repo (gemeten 2026-05-02):**
|
||||
|
||||
| Plek | Bestanden | Regels totaal | Grootste bestand |
|
||||
|---|---:|---:|---|
|
||||
| Root (CLAUDE.md, README.md, AGENTS.md, Brainstorm.md) | 4 | 679 | CLAUDE.md (340) |
|
||||
| `docs/` (root, exclusief subdirs) | 13 | 5.873 | architecture.md (1.247) |
|
||||
| `docs/patterns/` | 11 | 1.013 | dialog.md (387) |
|
||||
| `docs/plans/` | 8 | 2.121 | M10-qr-pairing-login.md (885) |
|
||||
| `.Plans/` (parallelle plan-historie) | 3 | ~600 | — |
|
||||
| **Totaal** | **39** | **~10.700** | — |
|
||||
|
||||
Bij elke turn die met `CLAUDE.md` start, wordt minimaal 340 regels orientation in de context geladen — vóór er één regel code is gelezen. De agent kan vervolgens uit ~9.000 regels documentatie het juiste fragment moeten kiezen op basis van bestandsnamen alleen, want er is geen front-matter en geen index.
|
||||
|
||||
---
|
||||
|
||||
## 2. Wat ik aantrof — review per laag
|
||||
|
||||
### 2.1 Root-niveau orientation
|
||||
|
||||
| Bestand | Wat het doet vandaag | Probleem |
|
||||
|---|---|---|
|
||||
| `CLAUDE.md` (340 r) | Doel, doc-index, twee start-tracks, tech stack, UI-conventies, patroon-index, env vars, conventies, branch/commit-strategie, scrum-terminologie, MCP, deployment, DoD | Té breed: oriëntatie + harde regels + referentie-tabellen + procedures. Alles wordt elke turn geladen. |
|
||||
| `AGENTS.md` (38 r) | Codex-variant van CLAUDE.md | Duplicatie: 80% overlapt met CLAUDE.md (access-control, doc-sync, verificatie). Twee waarheden die uit elkaar kunnen lopen. |
|
||||
| `README.md` (285 r) | Portfolio-pitch, stack, setup, routes, dev-flow | Mensgericht (recruiters, GitHub-bezoekers). Goed dat het bestaat — niet aanraken. |
|
||||
| `Brainstorm.md` (16 r) | Stukjes Prisma-schema, JSON-snippet en HTML-DOM-dump zonder context | **Dood bestand**, weghalen of verplaatsen naar `docs/scratch/`. |
|
||||
|
||||
### 2.2 `docs/` root
|
||||
|
||||
| Bestand | Regels | Waar het thuishoort |
|
||||
|---|---:|---|
|
||||
| `architecture.md` | 1.247 | `docs/architecture/` — splitsen (zie §4) |
|
||||
| `functional.md` | 650 | `docs/specs/functional.md` |
|
||||
| `backlog.md` | 751 | `docs/backlog/index.md` |
|
||||
| `product-backlog.md` | 454 | `docs/backlog/product-historical.md` (referentie, zie noot in CLAUDE.md) |
|
||||
| `personas.md` | 138 | `docs/specs/personas.md` |
|
||||
| `styling.md` | 670 | `docs/design/styling.md` |
|
||||
| `md3-color-scheme.md` | 941 | `docs/design/styling.md` (overlapt deels met `styling.md` — kandidaat voor merge) |
|
||||
| `test-plan.md` | 454 | `docs/qa/api-test-plan.md` |
|
||||
| `pbi-dialog.md` | 120 | `docs/specs/dialogs/pbi.md` |
|
||||
| `story-dialog.md` | 163 | `docs/specs/dialogs/story.md` |
|
||||
| `task-dialog.md` | 127 | `docs/specs/dialogs/task.md` |
|
||||
| `solo-paneel-spec.md` | 771 | `docs/specs/solo-panel.md` |
|
||||
| `api.md` | 520 | `docs/api/rest-contract.md` |
|
||||
| `decisions/agent-instructions-history.md` | 173 | `docs/decisions/agent-instructions.md` (ADR-stijl) |
|
||||
| `erd.svg`, `icons.html` | — | `docs/assets/` |
|
||||
|
||||
**Patroon dat opvalt:** alles met prefix `` — dat prefix is overbodig, je staat al in `docs/` van de Scrum4Me-repo. Verwijderen scheelt visuele ruis bij `ls`.
|
||||
|
||||
**Inconsistente capitalization:** één bestand `md3-color-scheme.md` (snake + UpperCamel), de rest kebab. Eén bestand `api.md` (UPPER), de rest lowercase.
|
||||
|
||||
### 2.3 `docs/patterns/`
|
||||
|
||||
11 patronen, elk 25–390 regels. Goed als concept, maar:
|
||||
|
||||
- `test.md` bevat letterlijk het woord "test" — junkfile, weghalen.
|
||||
- Geen front-matter; agent moet titel + intro lezen om te weten of het patroon van toepassing is.
|
||||
- Naamgeving inconsistent: `iron-session.md`, `qr-login.md`, `claude-question-channel.md` — sommige domeinspecifiek, andere generiek. Geen prefix die laat zien of het een **rule** (verplicht), **recipe** (voorbeeldcode) of **explainer** is.
|
||||
|
||||
### 2.4 `docs/plans/`
|
||||
|
||||
- 8 plans. Eén heeft een filename met spaties en em-dash: `tweede-claude-agent-planning.md` — breekt grep/glob/git-workflows op sommige shells, en is moeilijk te linken. Omnoemen naar `tweede-claude-agent-planning.md`.
|
||||
- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` (ook nog typo "rioriteiten") — externe locatie die niet in de repo zit en die de agent niet kan lezen.
|
||||
- `MEMORY.md` wordt op meerdere plaatsen genoemd maar bestaat niet in de repo.
|
||||
|
||||
### 2.5 `.Plans/` (root)
|
||||
|
||||
3 historische planfiles uit april 2026, parallel aan `docs/plans/`. Twee waarheden voor "waar staan plannen". Voorstel: archiveren naar `docs/plans/archive/` of weghalen.
|
||||
|
||||
### 2.6 Cross-referenties en dode links
|
||||
|
||||
- CLAUDE.md verwijst naar `docs/architecture.md#demo-user-policy` — die anchor bestaat (regel 1068 `## Demo-user policy (ST-1110)`), dus dit is OK; maar er bestaat geen lint die garandeert dat dit zo blijft als de header verandert.
|
||||
- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` — externe locatie buiten de repo, plus typo "rioriteiten". Een agent kan die niet lezen.
|
||||
- README.md verwijst niet naar CLAUDE.md/AGENTS.md (mensbezoekers vinden de agent-instructie laag niet).
|
||||
- Geen enkel doc heeft een "Zie ook"-blok aan de onderkant. Cross-navigatie tussen patroon ↔ spec ↔ plan moet de agent zelf reconstrueren.
|
||||
|
||||
### 2.7 Wat er níet is (en zou moeten)
|
||||
|
||||
- **Geen index/manifest.** Een agent die `glob "docs/**/*.md"` doet, krijgt 30+ paden zonder context.
|
||||
- **Geen front-matter.** Geen status (draft/active/deprecated), audience, last-updated, related.
|
||||
- **Geen ADR-laag.** Beslissingen zoals "waarom geen Radix maar @base-ui/react", "waarom float sort_order", "waarom one-branch-per-milestone" zitten verstrooid in CLAUDE.md, README en losse plans. Een `docs/decisions/`-folder met ADR-format zou ze vindbaar maken.
|
||||
- **Geen glossary.** Domeintermen (PBI, Story, Sprint, Solo, Todo, demo-token) zijn alleen impliciet gedefinieerd in de functional spec.
|
||||
- **Geen "lookup-hints" in de doc-index.** CLAUDE.md zegt *waarvoor* je een doc gebruikt, niet *wanneer je het NIET hoeft te lezen*.
|
||||
|
||||
---
|
||||
|
||||
## 3. Doelen voor de nieuwe structuur
|
||||
|
||||
In volgorde van belangrijkheid:
|
||||
|
||||
1. **Eén goedkope orientation-laag.** Een agent moet ≤150 regels lezen om te weten waar hij verder moet kijken.
|
||||
2. **Voorspelbare paden.** `docs/<topic>/<entity-or-feature>.md` zonder uitzonderingen.
|
||||
3. **Machine-leesbare metadata.** YAML-front-matter op élk doc met minimaal `status`, `audience`, `last_updated`, `related`.
|
||||
4. **Per-doc lookup-hint.** Eén zin "Lees dit als …" bovenaan; één zin "Niet hiervoor lezen: …" om verkeerd ophalen te voorkomen.
|
||||
5. **Splitsing van regels (verplicht) en uitleg (referentie).** Regels in een korte rule-doc; voorbeeldcode en rationale in een aparte recipe/explainer.
|
||||
6. **Eén bron-van-waarheid per onderwerp.** Geen Codex-vs-Claude-duplicatie; AGENTS.md wordt een 10-regelige verwijzing naar CLAUDE.md.
|
||||
|
||||
---
|
||||
|
||||
## 4. Voorgestelde doelstructuur
|
||||
|
||||
```
|
||||
/ (repo-root)
|
||||
├── README.md (mens, portfolio — ongewijzigd)
|
||||
├── CLAUDE.md (agent-orientation, ≤150 regels — zie §5)
|
||||
├── AGENTS.md (10 regels: "alles in CLAUDE.md geldt ook voor jou")
|
||||
├── docs/
|
||||
│ ├── INDEX.md (NIEUW — manifest met front-matter van alle docs)
|
||||
│ ├── glossary.md (NIEUW — PBI, Story, Sprint, demo-token, …)
|
||||
│ │
|
||||
│ ├── architecture/
|
||||
│ │ ├── overview.md (uit huidige architecture.md §1–§3)
|
||||
│ │ ├── data-model.md (uit §Datamodel + §Prisma Schema)
|
||||
│ │ ├── auth-and-sessions.md (uit §Authenticatieflow)
|
||||
│ │ ├── qr-pairing.md (uit §QR-pairing flow)
|
||||
│ │ ├── claude-question-channel.md (uit §Vraag-antwoord-kanaal)
|
||||
│ │ └── project-structure.md (uit §Projectstructuur)
|
||||
│ │
|
||||
│ ├── specs/
|
||||
│ │ ├── functional.md (huidige functional.md)
|
||||
│ │ ├── personas.md
|
||||
│ │ ├── solo-panel.md
|
||||
│ │ └── dialogs/
|
||||
│ │ ├── pbi.md
|
||||
│ │ ├── story.md
|
||||
│ │ └── task.md
|
||||
│ │
|
||||
│ ├── design/
|
||||
│ │ ├── styling.md (samengevoegd uit styling + MD3-color)
|
||||
│ │ └── color-tokens.md (alleen het token-overzicht)
|
||||
│ │
|
||||
│ ├── api/
|
||||
│ │ ├── rest-contract.md (huidige api.md)
|
||||
│ │ └── error-codes.md (afgesplitst — vandaag verspreid)
|
||||
│ │
|
||||
│ ├── patterns/ (RULES — kort en bindend)
|
||||
│ │ ├── 00-conventions.md (server-action, prisma-client, route-handler — kort)
|
||||
│ │ ├── dialog.md
|
||||
│ │ ├── sort-order.md
|
||||
│ │ ├── zustand-optimistic.md
|
||||
│ │ ├── iron-session.md
|
||||
│ │ ├── proxy.md (was middleware.md — nieuwe naam)
|
||||
│ │ ├── qr-pairing.md
|
||||
│ │ └── claude-question-channel.md
|
||||
│ │
|
||||
│ ├── recipes/ (NIEUW — uitgewerkte voorbeeldcode bij rules)
|
||||
│ │ └── … (één recipe per pattern dat code-snippets had)
|
||||
│ │
|
||||
│ ├── runbooks/ (NIEUW — operationele procedures)
|
||||
│ │ ├── deploy-vercel.md (uit CLAUDE.md §Deployment)
|
||||
│ │ ├── env-vars.md (uit CLAUDE.md §Env vars + .env.example)
|
||||
│ │ └── local-dev.md (huidige README §setup, geëxtraheerd)
|
||||
│ │
|
||||
│ ├── decisions/ (NIEUW — ADR-stijl)
|
||||
│ │ ├── 0001-base-ui-over-radix.md
|
||||
│ │ ├── 0002-float-sort-order.md
|
||||
│ │ ├── 0003-one-branch-per-milestone.md
|
||||
│ │ ├── 0004-status-enum-mapping.md
|
||||
│ │ └── 0005-agent-instructions.md (was decisions/agent-instructions-history.md)
|
||||
│ │
|
||||
│ ├── backlog/
|
||||
│ │ ├── index.md (huidige backlog.md)
|
||||
│ │ └── product-historical.md (huidige product-backlog.md)
|
||||
│ │
|
||||
│ ├── plans/
|
||||
│ │ ├── M9-active-product-backlog.md
|
||||
│ │ ├── M10-qr-pairing-login.md
|
||||
│ │ ├── M11-claude-questions.md
|
||||
│ │ ├── ST-1109-pbi-status.md
|
||||
│ │ ├── ST-1110-demo-readonly.md
|
||||
│ │ ├── ST-1111-claude-job-trigger.md
|
||||
│ │ ├── ST-1114-copilot-reviews.md
|
||||
│ │ ├── tweede-claude-agent-planning.md (rename — geen spaties/em-dash)
|
||||
│ │ └── archive/ (uit `.Plans/` aan repo-root)
|
||||
│ │ ├── 2026-04-27-claude-md-workflow-update.md
|
||||
│ │ ├── 2026-04-27-insert-milestone-tool.md
|
||||
│ │ └── 2026-04-27-m8-realtime-solo.md
|
||||
│ │
|
||||
│ ├── qa/
|
||||
│ │ └── api-test-plan.md
|
||||
│ │
|
||||
│ └── assets/
|
||||
│ ├── erd.svg
|
||||
│ └── icons.html
|
||||
│
|
||||
└── .Plans/ (WEG — naar docs/plans/archive/)
|
||||
└── Brainstorm.md (WEG — junk, of naar docs/scratch/)
|
||||
└── docs/patterns/test.md (WEG — junk)
|
||||
```
|
||||
|
||||
**Prefix `` overal weg.** Je staat in de Scrum4Me-repo.
|
||||
**Alle bestandsnamen kebab-case, lowercase.** Geen `api.md`, geen `MD3_…`.
|
||||
|
||||
---
|
||||
|
||||
## 5. CLAUDE.md herontwerp
|
||||
|
||||
CLAUDE.md wordt strikt **router + harde regels** — geen referentie-tabellen, geen voorbeelden, geen rationale.
|
||||
|
||||
Voorgestelde nieuwe inhoud (max ~150 regels):
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md — Scrum4Me
|
||||
|
||||
## 1. Wat is Scrum4Me
|
||||
(2 zinnen — link naar README voor de pitch)
|
||||
|
||||
## 2. Eerst lezen, altijd
|
||||
- docs/INDEX.md — manifest van alle docs
|
||||
- docs/glossary.md — bij twijfel over een term
|
||||
|
||||
## 3. Hoe je werk vindt
|
||||
Twee tracks (A: MCP, B: manueel) — verkort tot 10 regels.
|
||||
Detail: docs/runbooks/sprint-flow.md
|
||||
|
||||
## 4. Hardstop-regels (nooit overtreden)
|
||||
- demo-user heeft geen schrijfrechten (3-laagsdekking)
|
||||
- @base-ui/react, niet Radix
|
||||
- nooit bg-blue-500, altijd MD3-tokens
|
||||
- één commit = één verantwoordelijkheid
|
||||
- één branch per milestone, push pas na user-approval
|
||||
- denormalized FKs uit DB-parent, niet uit client-input
|
||||
(elk punt → 1 regel + link naar pattern/decision)
|
||||
|
||||
## 6. Stack op één regel per laag
|
||||
(geen versie-uitleg, link naar docs/architecture/overview.md)
|
||||
|
||||
## 7. Snelreferentie patronen
|
||||
| Wanneer | Lees |
|
||||
|---|---|
|
||||
| Server Action schrijven | docs/patterns/server-action.md |
|
||||
| Drag-and-drop reorder | docs/patterns/sort-order.md |
|
||||
| …(max 10 rijen)…|
|
||||
|
||||
## 8. Verificatie vóór hand-off
|
||||
`npm run lint && npm test && npm run build`
|
||||
```
|
||||
|
||||
Alles wat nu in CLAUDE.md §Conventies, §Branch & PR Strategy, §Commit Strategy, §MCP-integratie, §Deployment staat → verhuist naar:
|
||||
- `docs/runbooks/branch-and-commit.md` (regels + voorbeelden samen)
|
||||
- `docs/runbooks/deploy-vercel.md`
|
||||
- `docs/runbooks/mcp-integration.md`
|
||||
- `docs/decisions/0003-one-branch-per-milestone.md` (waarom)
|
||||
|
||||
CLAUDE.md houdt in §4 alleen de éénregelige regel + link.
|
||||
|
||||
**Effect:** elke turn 150 r in plaats van 340 r aan orientation-context. De agent leest aanvullende docs alleen wanneer de huidige taak ze raakt.
|
||||
|
||||
---
|
||||
|
||||
## 6. Front-matter spec
|
||||
|
||||
Élk markdown-bestand in `docs/` (en `CLAUDE.md`, `AGENTS.md`) krijgt bovenaan:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: <korte titel>
|
||||
status: draft | active | deprecated
|
||||
audience: ai-agent | maintainer | contributor | external
|
||||
language: nl | en
|
||||
last_updated: 2026-05-02
|
||||
applies_to: [feature-of-module-of-milestone-keys] # optioneel
|
||||
related:
|
||||
- docs/<andere>.md
|
||||
- CLAUDE.md
|
||||
when_to_read: <één zin>
|
||||
do_not_read_for: <één zin — voorkomt mis-fetch>
|
||||
---
|
||||
```
|
||||
|
||||
**Waarom dit voor AI-lookup helpt:**
|
||||
|
||||
- `status: deprecated` → agent slaat het over zonder te lezen.
|
||||
- `applies_to: [M10, qr-login]` → grep op milestone-key → directe hit.
|
||||
- `when_to_read` / `do_not_read_for` → agent kan beslissen op de eerste 20 regels of dit doc nuttig is, zonder de hele 800-regelige spec in te lezen.
|
||||
- `related` → expliciete graaf in plaats van impliciete cross-refs.
|
||||
|
||||
`docs/INDEX.md` wordt automatisch gegenereerd uit deze front-matter (klein script in `scripts/build-docs-index.ts` — onderdeel van het migratieplan).
|
||||
|
||||
---
|
||||
|
||||
## 7. AGENTS.md herontwerp
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
This repo's source of truth for agent instructions is **CLAUDE.md**.
|
||||
Codex, Cursor, Continue, and any other coding agent: read CLAUDE.md first.
|
||||
The same product, security, and verification rules apply regardless of which agent runs.
|
||||
|
||||
Repo-specific addendum (only if your agent does NOT speak markdown well):
|
||||
- The "This is NOT the Next.js you know" note also applies to you.
|
||||
- Run `npm run lint && npm test && npm run build` before handing work back.
|
||||
```
|
||||
|
||||
Geen duplicatie van access-control of doc-sync — die regels staan exclusief in CLAUDE.md / `docs/patterns/` / `docs/decisions/`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Migratie in fases
|
||||
|
||||
Elke fase is een eigen branch + PR. Geen big-bang. Volgorde gekozen zodat agents tijdens de migratie nog steeds werken.
|
||||
|
||||
### Fase 1 — Junk weg, front-matter erbij (laag risico)
|
||||
|
||||
- `docs/patterns/test.md` weghalen.
|
||||
- `Brainstorm.md` weghalen of `docs/scratch/brainstorm-2026-05.md`.
|
||||
- `.Plans/` → `docs/plans/archive/`.
|
||||
- Front-matter toevoegen aan élk bestaand bestand (zonder verplaatsen). Status default = `active`.
|
||||
- `docs/INDEX.md` genereren via script.
|
||||
|
||||
**Voor commit:** alle bestaande paden werken nog. Geen risico voor lopende sessies of CI.
|
||||
|
||||
### Fase 2 — Naamgeving normaliseren
|
||||
|
||||
- `` prefix overal weg via `git mv` (1 commit per groep — backlog/specs/personas/styling/dialogs).
|
||||
- `api.md` → `api/rest-contract.md`.
|
||||
- `md3-color-scheme.md` → `design/md3-color-scheme.md`.
|
||||
- `tweede-claude-agent-planning.md` → `plans/tweede-claude-agent-planning.md`.
|
||||
- `middleware.md` → `proxy.md` (volgt Next.js 16 hernoeming).
|
||||
- Per `git mv`: in dezelfde commit zoek-en-vervang alle interne links + CLAUDE.md doc-index.
|
||||
|
||||
### Fase 3 — Folder-taxonomie
|
||||
|
||||
- Maak `docs/architecture/`, `docs/specs/`, `docs/design/`, `docs/api/`, `docs/runbooks/`, `docs/decisions/`, `docs/backlog/`, `docs/qa/`, `docs/assets/`.
|
||||
- Verplaats per groep met `git mv`. Eén commit per groep.
|
||||
- Update CLAUDE.md doc-index per stap.
|
||||
|
||||
### Fase 4 — Splits monolithische docs
|
||||
|
||||
- `architecture.md` (1.247 r) opdelen in 6 docs onder `docs/architecture/`.
|
||||
- Originele file wordt 20 regels: titel + "Dit document is opgesplitst — zie:" + lijst met nieuwe paden.
|
||||
- Idem voor `solo-paneel-spec.md` als dat onderdelen heeft die naar specs én patterns kunnen.
|
||||
|
||||
### Fase 5 — CLAUDE.md verkorten + AGENTS.md verkorten
|
||||
|
||||
- Knip CLAUDE.md naar het skelet uit §5.
|
||||
- Verplaats verwijderde secties naar `docs/runbooks/` en `docs/decisions/`.
|
||||
- AGENTS.md vervangen door de versie uit §7.
|
||||
|
||||
### Fase 6 — ADR-backfill
|
||||
|
||||
- Schrijf ADR's voor de impliciete beslissingen (5–8 stuks):
|
||||
1. base-ui-over-radix
|
||||
2. float-sort-order
|
||||
3. one-branch-per-milestone
|
||||
4. status-enum-mapping (db UPPER ↔ api lower)
|
||||
5. iron-session-over-nextauth
|
||||
6. demo-user-policy (3-laags)
|
||||
7. claude-question-channel-design
|
||||
8. agent-instructions-policy (was audit)
|
||||
|
||||
### Fase 7 — Glossary + index-script
|
||||
|
||||
- `docs/glossary.md` schrijven (PBI, Story, Sprint, Solo, Todo, demo-token, MCP-job, …).
|
||||
- `scripts/build-docs-index.ts` — genereert `docs/INDEX.md` uit alle front-matters.
|
||||
- Husky pre-commit hook: index regenereren bij wijziging van front-matter.
|
||||
|
||||
### Fase 8 — Cross-link-check
|
||||
|
||||
- Klein script dat alle `docs/...md` links volgt en rapporteert dode links én anchor-misses.
|
||||
- Toevoegen aan `npm run lint` of `npm test`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Wat dit oplevert (meetbaar)
|
||||
|
||||
| Metric | Vandaag | Doel |
|
||||
|---|---:|---:|
|
||||
| Regels die elke agent-turn standaard in context komen (CLAUDE.md) | 340 | ≤150 |
|
||||
| Doc-bestanden in `docs/` root | 13 | 2 (INDEX.md, glossary.md) |
|
||||
| Doc-bestanden zonder front-matter | 36 | 0 |
|
||||
| Junk-bestanden | 3 (test.md, Brainstorm.md, .Plans/) | 0 |
|
||||
| Bestandsnamen met spaties of niet-ASCII | 1 | 0 |
|
||||
| Filename-prefixen die geen informatie toevoegen (``) | 8 | 0 |
|
||||
| Documenten >800 regels | 4 | 0 (na splitsing) |
|
||||
| Dode interne links | onbekend | 0 (na lint) |
|
||||
|
||||
---
|
||||
|
||||
## 10. Wat dit níet oplevert (eerlijk)
|
||||
|
||||
- Codequaliteit verbetert niet automatisch.
|
||||
- Patronen die nu fout zijn worden niet gefixt — alleen vindbaar gemaakt.
|
||||
- ADR's invullen kost denkwerk dat ik niet uit jouw hoofd kan halen — fase 6 vereist jouw input.
|
||||
- AI-agents die geen front-matter parseren (oudere modellen, sommige codex-flavors) profiteren minder. Voor de `docs/INDEX.md` is het wel platte tekst — die helpt iedereen.
|
||||
|
||||
---
|
||||
|
||||
## 11. Open beslissingen — status
|
||||
|
||||
| # | Vraag | Besluit (2026-05-02) |
|
||||
|---|---|---|
|
||||
| 1 | Taal van docs, front-matter, INDEX.md | **English** — alle nieuwe en herschreven docs in het Engels. Code comments blijven Engels (al zo). UI-strings blijven Nederlands. |
|
||||
| 2 | MD3-color + styling samenvoegen | **Eén doc** — `docs/design/styling.md`. |
|
||||
| 3 | `solo-paneel-spec.md` | **Samenvoegen** — opgaan in `docs/specs/functional.md` (eigen sectie). |
|
||||
| 4 | `.Plans/` archief | **Bewaren** — verplaatsen naar `docs/plans/archive/`. |
|
||||
| 5 | ADR-template (Nygard vs MADR) | **In discussie** — referentielink gedeeld, ik heb die niet kunnen openen (claude.ai share staat niet op de fetch-allowlist). Default voor fase 6: Nygard, klein en passend bij solo + kleine repo. Vervangbaar zodra besluit valt. |
|
||||
| 6 | Index-generator | **Node-script** in `scripts/build-docs-index.ts`. |
|
||||
|
||||
## 12. Implicaties van besluit 1 — taalwissel
|
||||
|
||||
De keuze "alle docs Engels" is groter dan hij lijkt. Drie scope-niveaus:
|
||||
|
||||
**Niveau A — going-forward only (kleinste scope):**
|
||||
- Élk nieuw doc en élke nieuw aangemaakte front-matter in het Engels.
|
||||
- Dit plan, INDEX.md, glossary.md, runbooks/, decisions/ — allemaal Engels vanaf creatie.
|
||||
- Bestaande Nederlandse docs blijven staan tot ze om een andere reden geraakt worden.
|
||||
- **Risico:** mengvormen in docs/ — een agent vindt ene helft Engels, andere helft Nederlands. Grep op een Engels keyword mist Nederlandse hits.
|
||||
|
||||
**Niveau B — opportunistic (middel):**
|
||||
- Niveau A + élke doc die we aanraken voor de restructuur (renames, splitsingen, front-matter toevoegen) wordt meteen vertaald.
|
||||
- Aan het eind van fase 5 zijn `architecture/`, `specs/`, `design/`, `api/`, `patterns/`, `runbooks/`, `decisions/` allemaal Engels.
|
||||
- Backlog, plans en QA blijven Nederlands tenzij ze ge-edit worden.
|
||||
|
||||
**Niveau C — full sweep:**
|
||||
- Élke `.md` in de repo vertalen, ongeacht of de restructuur hem aanraakt.
|
||||
- Aanzienlijk werk: ~10.700 regels prose. Schatting: 1-2 dagen agent-tijd of een batch-translate-pass met review.
|
||||
|
||||
**Voorstel: niveau B.** Sluit aan bij de migratiefases zonder een aparte translation-sprint te hoeven plannen. Niveau C kan later als één losse PR.
|
||||
|
||||
## 13. ADR-template — voorlopige keuze
|
||||
|
||||
Tot besluit valt op vraag 5: ik gebruik **Nygard-Light** als template voor fase 6. Eén ADR is één bestand met:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: <decision title>
|
||||
adr_number: 0001
|
||||
status: proposed | accepted | superseded by 00xx
|
||||
date: 2026-05-02
|
||||
---
|
||||
|
||||
# 0001. <decision title>
|
||||
|
||||
## Context
|
||||
Why this decision matters now. What forces are in play.
|
||||
|
||||
## Decision
|
||||
The choice we make. One paragraph, declarative.
|
||||
|
||||
## Consequences
|
||||
What becomes easier, what becomes harder, what we accept.
|
||||
```
|
||||
|
||||
Compact, grep-vriendelijk, en agent-leesbaar binnen ~30 regels. Als MADR de uitkomst wordt, swappen we het template voor fase 6 — alle eerdere fases zijn template-onafhankelijk.
|
||||
|
||||
## 14. Volgende stap
|
||||
|
||||
Met deze besluiten kan ik fase 1 omzetten naar een concrete uitvoeringslijst:
|
||||
|
||||
- exacte `rm` / `git mv` / `mkdir` commando's
|
||||
- de front-matter-template in het Engels
|
||||
- één `npm run` of bash-snippet die de hele fase in één commit zet
|
||||
- bijbehorende update-diff voor CLAUDE.md (alleen de doc-index-tabel)
|
||||
|
||||
Zeg het woord en ik produceer dat als `docs/plans/docs-restructure-phase-1.md`.
|
||||
|
||||
---
|
||||
|
||||
## Verificatie van dit plan
|
||||
|
||||
- [x] Bestandsnamen en regelaantallen gecheckt tegen `find docs -type f` + `wc -l` op disk (2026-05-02).
|
||||
- [x] Cross-refs in CLAUDE.md gegrep't en op bestaan getoetst.
|
||||
- [x] Geen voorgestelde nieuwe paden conflicteren met bestaande.
|
||||
- [x] Open beslissingen (§11) afgehandeld door maintainer (2026-05-02) — vraag 5 voorlopig op default.
|
||||
- [ ] ADR-template definitief vastgesteld (vraag 5).
|
||||
- [ ] Migratie fase 1 omgezet naar uitvoerbaar PR-plan (`docs/plans/docs-restructure-phase-1.md`).
|
||||
783
docs/plans/docs-restructure-pbi-spec.md
Normal file
783
docs/plans/docs-restructure-pbi-spec.md
Normal file
|
|
@ -0,0 +1,783 @@
|
|||
---
|
||||
spec_version: 1
|
||||
spec_type: pbi-bulk-create
|
||||
generated_at: 2026-05-02
|
||||
language: en
|
||||
notes: |
|
||||
Input for a bulk-create executor that calls
|
||||
mcp__scrum4me__create_pbi
|
||||
mcp__scrum4me__create_story
|
||||
mcp__scrum4me__create_task
|
||||
in that order. The executor reads the YAML graph at the bottom of this
|
||||
file. The prose above the graph is identical to what the executor sends
|
||||
as the PBI's `description` field, so any agent that later picks up a
|
||||
task gets the full context via mcp__scrum4me__get_claude_context.
|
||||
|
||||
product_id is intentionally left as a placeholder (REPLACE_ME) — fill it
|
||||
in before running the executor. priority uses 1 = critical … 5 = trivial.
|
||||
sort_order is omitted everywhere; the MCP server auto-assigns last+1
|
||||
within the priority group.
|
||||
---
|
||||
|
||||
# PBI Bulk-Create Spec — Docs-Restructure for AI-Optimized Lookup
|
||||
|
||||
## 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))
|
||||
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.
|
||||
|
||||
### Why this PBI exists
|
||||
|
||||
Today an agent loads `CLAUDE.md` (340 lines) every turn before reading a
|
||||
single line of code, then has to choose from 35 docs in `docs/` whose
|
||||
purpose is only inferable from the filename — there is no front-matter,
|
||||
no index, no machine-readable status. After this PBI, the agent reads
|
||||
`CLAUDE.md` (≤150 lines) plus `docs/INDEX.md` and knows where to go.
|
||||
|
||||
### Going-forward defaults — every task must respect these
|
||||
|
||||
- **Language:** all new and touched docs in English. Code comments stay
|
||||
English (already the case). UI strings stay Dutch.
|
||||
- **Front-matter:** every `.md` under `docs/` (and `CLAUDE.md`,
|
||||
`AGENTS.md`) carries YAML front-matter with at minimum
|
||||
`title`, `status`, `audience`, `language`, `last_updated`. Add
|
||||
`related`, `when_to_read`, `do_not_read_for` where useful.
|
||||
- **Naming:** lowercase kebab-case. No `` prefix. No spaces in
|
||||
filenames. No UPPER. Files matching `_*.md` are personal sidecar and
|
||||
excluded from the index.
|
||||
- **Commits:** one commit per logical layer. Use `docs(<story-slug>):`
|
||||
as the prefix when no ST-code applies. Reference the matching story
|
||||
slug from this spec (e.g. `docs(naming): drop prefix`).
|
||||
- **Pushing:** never push without explicit user approval. Local commits
|
||||
on the feature branch only. The branch convention is
|
||||
`feat/docs-restructure-<phase-slug>` (one branch per story).
|
||||
- **Cross-references:** when renaming or moving a file, update every
|
||||
internal link to it in the same commit. After the link-check story
|
||||
(Story 8) is done, run `npm run docs:check-links` before each commit.
|
||||
|
||||
### Sequencing
|
||||
|
||||
Stories run in numeric order. Story N+1 assumes the changes from Story N
|
||||
are merged. If you pick up a task and earlier stories aren't done, stop
|
||||
and surface it — don't try to leapfrog. The exception is Story 6
|
||||
(ADR-backfill) and Story 7 (glossary): both are content-only and can run
|
||||
in parallel with Stories 3–5 if you want.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Translating Dutch docs that this PBI doesn't otherwise touch — that's
|
||||
a separate full-sweep PR.
|
||||
- Code changes outside `docs/`, `scripts/`, `package.json`, `.gitignore`.
|
||||
- Pushing branches or opening PRs against `main`.
|
||||
- Restyling, content rewrites beyond what each task asks for.
|
||||
|
||||
### Where to look first
|
||||
|
||||
- This file (the PBI context block above).
|
||||
- [`docs/plans/docs-restructure-ai-lookup.md`](./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
|
||||
Story 6.
|
||||
|
||||
### Definition of done for this PBI
|
||||
|
||||
- All 8 stories' tasks accepted.
|
||||
- `docs/INDEX.md` regenerates without errors and lists every doc grouped
|
||||
correctly.
|
||||
- `npm run docs:check-links` passes (after Story 8).
|
||||
- `CLAUDE.md` ≤ 150 lines.
|
||||
- Zero docs without front-matter.
|
||||
- Zero junk files (`docs/patterns/test.md`, `Brainstorm.md` at root,
|
||||
`.Plans/` at root) remain.
|
||||
|
||||
---
|
||||
|
||||
## 2. Resolved decisions (quick reference)
|
||||
|
||||
| # | Question | Decision |
|
||||
|---|---|---|
|
||||
| 1 | Doc language | English for all new/touched docs |
|
||||
| 2 | MD3-color + styling | Merge into one `docs/design/styling.md` |
|
||||
| 3 | `solo-paneel-spec.md` | Merge into `docs/specs/functional.md` |
|
||||
| 4 | `.Plans/` | Archive under `docs/plans/archive/` |
|
||||
| 5 | ADR template | Nygard default; MADR for auth, queue, agent integration |
|
||||
| 6 | Index generator | Node script (`scripts/generate-docs-index.mjs`, already exists) |
|
||||
|
||||
---
|
||||
|
||||
## 3. What's already done (do not re-do)
|
||||
|
||||
These commits on `feat/docs-adr-and-index` already shipped:
|
||||
|
||||
- `docs(plans):` the restructure plan itself.
|
||||
- `docs(adr):` ADR scaffolding — templates, README, meta-ADR (0000).
|
||||
- `feat(docs):` the docs index generator + initial `docs/INDEX.md`.
|
||||
- `chore:` `.gitignore` for `.obsidian/` + `_*.md`.
|
||||
|
||||
So Story 6 only needs the **content** (the actual ADR-0001 … 0008
|
||||
files); Story 7 only needs the **glossary + husky hook**, the script
|
||||
already exists.
|
||||
|
||||
---
|
||||
|
||||
## 4. Structured graph (executor reads this)
|
||||
|
||||
```yaml
|
||||
pbi:
|
||||
product_id: REPLACE_ME
|
||||
title: "Docs-restructure for AI-optimized lookup"
|
||||
description: |
|
||||
See section 1 (Context) above. Every task in this PBI must respect:
|
||||
- English for new/touched docs (UI strings stay Dutch).
|
||||
- YAML front-matter on every doc (title, status, audience, language,
|
||||
last_updated; related/when_to_read/do_not_read_for where useful).
|
||||
- kebab-case, lowercase, no prefix, no spaces.
|
||||
- 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.
|
||||
priority: 2
|
||||
|
||||
stories:
|
||||
|
||||
- slug: junk-cleanup-and-front-matter
|
||||
title: "Phase 1 — Junk cleanup + front-matter on every doc"
|
||||
description: |
|
||||
Lowest-risk first phase. Remove stub/junk files, archive parallel
|
||||
plan folder, and add YAML front-matter to every existing .md
|
||||
under docs/. No paths change yet — every existing link still
|
||||
works after this story.
|
||||
acceptance_criteria: |
|
||||
- docs/patterns/test.md is deleted.
|
||||
- .Plans/ is moved to docs/plans/archive/ and the .gitignore
|
||||
entry for .Plans/ is removed.
|
||||
- Brainstorm.md at repo root is deleted (or moved to
|
||||
docs/scratch/) — it's already gitignored.
|
||||
- Every existing .md under docs/ (and CLAUDE.md, AGENTS.md) has
|
||||
YAML front-matter with at least title, status, audience,
|
||||
language, last_updated.
|
||||
- `npm run docs:index` reports 0 docs missing front-matter and
|
||||
regenerates docs/INDEX.md cleanly.
|
||||
priority: 2
|
||||
tasks:
|
||||
|
||||
- title: "Remove docs/patterns/test.md"
|
||||
description: "One-word stub file (`test`) committed by accident."
|
||||
implementation_plan: |
|
||||
git rm docs/patterns/test.md
|
||||
grep -rn "patterns/test" docs/ CLAUDE.md AGENTS.md README.md
|
||||
# expect no matches
|
||||
commit: docs(junk-cleanup): remove stub patterns/test.md
|
||||
priority: 3
|
||||
|
||||
- title: "Archive .Plans/ into docs/plans/archive/"
|
||||
description: "Three historical plan files at repo root parallel to docs/plans/."
|
||||
implementation_plan: |
|
||||
mkdir -p docs/plans/archive
|
||||
git mv .Plans/2026-04-27-claude-md-workflow-update.md docs/plans/archive/
|
||||
git mv .Plans/2026-04-27-insert-milestone-tool.md docs/plans/archive/
|
||||
git mv .Plans/2026-04-27-m8-realtime-solo.md docs/plans/archive/
|
||||
rmdir .Plans
|
||||
# remove the .Plans/ entry from .gitignore (line 55 today)
|
||||
commit: docs(junk-cleanup): archive .Plans/ to docs/plans/archive/
|
||||
priority: 3
|
||||
|
||||
- title: "Delete root Brainstorm.md"
|
||||
description: "Already gitignored; contains stray Prisma + DOM dump with no context."
|
||||
implementation_plan: |
|
||||
git rm -f Brainstorm.md
|
||||
# leave the .gitignore Brainstorm.md entry — harmless if file gone
|
||||
commit: docs(junk-cleanup): remove root Brainstorm.md scratch file
|
||||
priority: 4
|
||||
|
||||
- title: "Add front-matter to all docs/*.md (root)"
|
||||
description: "13 files at docs/ root currently have no front-matter."
|
||||
implementation_plan: |
|
||||
For each file in docs/*.md (excluding INDEX.md):
|
||||
prepend a YAML block:
|
||||
---
|
||||
title: <copy from H1>
|
||||
status: active
|
||||
audience: [maintainer, contributor]
|
||||
language: nl # or en, match the actual file
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
Verify: head -1 docs/*.md | grep -c '^==>' should equal
|
||||
(count of files), and head -2 docs/*.md should show "---" on
|
||||
line 2 of every file.
|
||||
commit: docs(front-matter): add YAML front-matter to docs/ root
|
||||
priority: 2
|
||||
|
||||
- title: "Add front-matter to docs/patterns/*.md"
|
||||
description: "11 patterns get front-matter with audience=ai-agent."
|
||||
implementation_plan: |
|
||||
For each docs/patterns/*.md:
|
||||
---
|
||||
title: <H1 minus 'Patroon: ' prefix>
|
||||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-02
|
||||
when_to_read: <one sentence — what triggers reading this>
|
||||
---
|
||||
commit: docs(front-matter): add YAML front-matter to patterns/
|
||||
priority: 2
|
||||
|
||||
- title: "Add front-matter to docs/plans/*.md and CLAUDE.md/AGENTS.md"
|
||||
description: "Plans, the orientation file, and AGENTS.md."
|
||||
implementation_plan: |
|
||||
Plans (active + archive): include `applies_to: [<milestone>]`
|
||||
and `status: <proposal|active|done|deprecated>` based on git
|
||||
history of the file.
|
||||
CLAUDE.md and AGENTS.md: status: active, audience: ai-agent.
|
||||
commit: docs(front-matter): add YAML front-matter to plans + agent files
|
||||
priority: 2
|
||||
|
||||
- title: "Verify INDEX.md picks up new metadata"
|
||||
description: "Sanity check: status and dates now visible in INDEX.md."
|
||||
implementation_plan: |
|
||||
npm run docs:index
|
||||
grep -c "| — |" docs/INDEX.md
|
||||
# expect significantly fewer than before (most rows now
|
||||
# show real status/date)
|
||||
commit: docs(index): regenerate INDEX.md after front-matter pass
|
||||
priority: 3
|
||||
|
||||
- slug: naming-normalization
|
||||
title: "Phase 2 — Normalize file naming"
|
||||
description: |
|
||||
Drop the `` prefix. Lowercase everything. Remove the
|
||||
space + em-dash filename. Rename Next.js 16 middleware to proxy.
|
||||
After this story all filenames are kebab-case and grep-friendly.
|
||||
acceptance_criteria: |
|
||||
- No file under docs/ starts with ``.
|
||||
- No file under docs/ uses UPPER, snake_case, or contains spaces.
|
||||
- docs/patterns/proxy.md is renamed to docs/patterns/proxy.md.
|
||||
- Every internal link to renamed files is updated in the same
|
||||
commit as the rename.
|
||||
- `npm run docs:index` runs cleanly with no missing files.
|
||||
priority: 2
|
||||
tasks:
|
||||
|
||||
- title: "Rename docs/* (drop prefix)"
|
||||
description: "8 spec/backlog/styling files at docs/ root."
|
||||
implementation_plan: |
|
||||
git mv docs/architecture.md docs/architecture.md
|
||||
git mv docs/backlog/index.md docs/backlog/index.md
|
||||
git mv docs/specs/functional.md docs/specs/functional.md
|
||||
git mv docs/specs/dialogs/pbi.md docs/specs/dialogs/pbi.md
|
||||
git mv docs/specs/personas.md docs/specs/personas.md
|
||||
git mv docs/backlog/product-historical.md docs/backlog/product-historical.md
|
||||
git mv docs/specs/dialogs/story.md docs/specs/dialogs/story.md
|
||||
git mv docs/design/styling.md docs/design/styling.md
|
||||
git mv docs/specs/dialogs/task.md docs/specs/dialogs/task.md
|
||||
git mv docs/qa/api-test-plan.md docs/qa/api-test-plan.md
|
||||
# update every internal link
|
||||
grep -rln "" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|||g'
|
||||
npm run docs:index
|
||||
commit: docs(naming): drop prefix from doc filenames
|
||||
priority: 2
|
||||
|
||||
- title: "Lowercase api.md and MD3 file"
|
||||
description: "Two files use non-kebab capitalization."
|
||||
implementation_plan: |
|
||||
git mv docs/api/rest-contract.md docs/api/rest-contract.md
|
||||
git mv docs/design/styling.md docs/design/styling.md
|
||||
grep -rln "API\.md\|MD3_Color_Scheme" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|API\.md|api.md|g; s|md3-color-scheme|md3-color-scheme|g'
|
||||
npm run docs:index
|
||||
commit: docs(naming): lowercase api.md and MD3 filenames
|
||||
priority: 2
|
||||
|
||||
- title: "Rename plan file with spaces + em-dash"
|
||||
description: "`tweede-claude-agent-planning.md` → kebab-case."
|
||||
implementation_plan: |
|
||||
git mv "docs/plans/tweede-claude-agent-planning.md" \
|
||||
docs/plans/tweede-claude-agent-planning.md
|
||||
grep -rln "Tweede Claude Agent" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|Tweede Claude Agent — Planning Agent\.md|tweede-claude-agent-planning.md|g'
|
||||
npm run docs:index
|
||||
commit: docs(naming): rename plan file to kebab-case ASCII
|
||||
priority: 3
|
||||
|
||||
- title: "Rename middleware.md → proxy.md"
|
||||
description: "Next.js 16 renamed middleware.ts to proxy.ts."
|
||||
implementation_plan: |
|
||||
git mv docs/patterns/proxy.md docs/patterns/proxy.md
|
||||
grep -rln "patterns/proxy" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|patterns/proxy|patterns/proxy|g'
|
||||
npm run docs:index
|
||||
commit: docs(naming): rename middleware.md to proxy.md (next 16)
|
||||
priority: 3
|
||||
|
||||
- title: "Update CLAUDE.md doc-index table"
|
||||
description: "After renames, CLAUDE.md §Specificatiedocumenten and §Implementatiepatronen tables need a sweep."
|
||||
implementation_plan: |
|
||||
Manually review CLAUDE.md lines 13–32 (specs table) and
|
||||
99–118 (patterns table) — the sed sweeps already updated the
|
||||
paths, but column wording may need a quick polish.
|
||||
commit: docs(naming): polish CLAUDE.md doc-index after renames
|
||||
priority: 3
|
||||
|
||||
- slug: folder-taxonomy
|
||||
title: "Phase 3 — Move docs into topical folders"
|
||||
description: |
|
||||
Create architecture/, specs/, design/, api/, runbooks/,
|
||||
decisions/, backlog/, qa/, assets/ folders. Move existing files
|
||||
into them. Keep one git mv per group so commits stay readable.
|
||||
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.
|
||||
- Internal links updated in the same commit as each move.
|
||||
- `npm run docs:index` shows docs grouped correctly.
|
||||
priority: 2
|
||||
tasks:
|
||||
|
||||
- title: "Create folder skeleton"
|
||||
description: "Empty folders with .gitkeep so structure is visible."
|
||||
implementation_plan: |
|
||||
for d in architecture specs specs/dialogs design api runbooks decisions backlog qa assets; do
|
||||
mkdir -p docs/$d
|
||||
touch docs/$d/.gitkeep
|
||||
done
|
||||
commit: docs(taxonomy): scaffold topical folders under docs/
|
||||
priority: 3
|
||||
|
||||
- title: "Move spec files into docs/specs/"
|
||||
description: "functional, personas, dialogs/."
|
||||
implementation_plan: |
|
||||
git mv docs/specs/functional.md docs/specs/functional.md
|
||||
git mv docs/specs/personas.md docs/specs/personas.md
|
||||
git mv docs/specs/dialogs/pbi.md docs/specs/dialogs/pbi.md
|
||||
git mv docs/specs/dialogs/story.md docs/specs/dialogs/story.md
|
||||
git mv docs/specs/dialogs/task.md docs/specs/dialogs/task.md
|
||||
grep -rln "docs/specs/personas\|docs/specs/functional\|docs/.*-dialog" \
|
||||
docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' \
|
||||
-e 's|docs/specs/functional|docs/specs/functional|g' \
|
||||
-e 's|docs/specs/personas|docs/specs/personas|g' \
|
||||
-e 's|docs/specs/dialogs/pbi|docs/specs/dialogs/pbi|g' \
|
||||
-e 's|docs/specs/dialogs/story|docs/specs/dialogs/story|g' \
|
||||
-e 's|docs/specs/dialogs/task|docs/specs/dialogs/task|g'
|
||||
commit: docs(taxonomy): move spec files into docs/specs/
|
||||
priority: 2
|
||||
|
||||
- title: "Move design + api + qa + backlog + assets"
|
||||
description: "Bulk move per topic."
|
||||
implementation_plan: |
|
||||
git mv docs/design/styling.md docs/design/styling.md
|
||||
git mv docs/design/styling.md docs/design/styling.md
|
||||
git mv docs/api/rest-contract.md docs/api/rest-contract.md
|
||||
git mv docs/qa/api-test-plan.md docs/qa/api-test-plan.md
|
||||
git mv docs/backlog/index.md docs/backlog/index.md
|
||||
git mv docs/backlog/product-historical.md docs/backlog/product-historical.md
|
||||
git mv docs/assets/erd.svg docs/assets/erd.svg
|
||||
git mv docs/assets/icons.html docs/assets/icons.html
|
||||
# update links — sed sweep
|
||||
commit: docs(taxonomy): move design/api/qa/backlog/assets into folders
|
||||
priority: 2
|
||||
|
||||
- title: "Move decisions/agent-instructions-history → decisions/ as ADR seed"
|
||||
description: "Sets up Story 6 ADR-0008 (will replace this file with a real ADR)."
|
||||
implementation_plan: |
|
||||
git mv docs/decisions/agent-instructions-history.md docs/decisions/agent-instructions-history.md
|
||||
grep -rln "decisions/agent-instructions-history" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|decisions/agent-instructions-history|decisions/agent-instructions-history|g'
|
||||
commit: docs(taxonomy): move decisions/agent-instructions-history into decisions/
|
||||
priority: 3
|
||||
|
||||
- slug: split-monoliths
|
||||
title: "Phase 4 — Split oversized docs"
|
||||
description: |
|
||||
Four docs exceed 800 lines and conflate multiple topics. Split
|
||||
them so an agent can grep for the right section directly.
|
||||
acceptance_criteria: |
|
||||
- No doc in docs/ exceeds 800 lines.
|
||||
- The original location of each split doc still exists as a
|
||||
breadcrumb file (≤25 lines) listing the new paths so old links
|
||||
fail gracefully.
|
||||
- solo-panel content lives inside docs/specs/functional.md as
|
||||
its own H2 section.
|
||||
- md3-color-scheme.md content is merged into docs/design/styling.md.
|
||||
priority: 2
|
||||
tasks:
|
||||
|
||||
- title: "Split docs/architecture.md into 6 files under docs/architecture/"
|
||||
description: "Current size: 1247 lines."
|
||||
implementation_plan: |
|
||||
Target split (per plan §4):
|
||||
docs/architecture/overview.md (today §1–§3)
|
||||
docs/architecture/data-model.md (Datamodel + Prisma Schema)
|
||||
docs/architecture/auth-and-sessions.md (Authenticatieflow)
|
||||
docs/architecture/qr-pairing.md (QR-pairing flow)
|
||||
docs/architecture/claude-question-channel.md (Q&A kanaal)
|
||||
docs/architecture/project-structure.md (Projectstructuur)
|
||||
Replace docs/specs/architecture.md (after Phase 3 it's at
|
||||
docs/architecture.md still — adjust path) with a 20-line
|
||||
breadcrumb pointing to the six new files.
|
||||
Each new file gets fresh front-matter.
|
||||
commit: docs(split): break architecture.md into 6 topical files
|
||||
priority: 2
|
||||
|
||||
- title: "Merge solo-paneel-spec.md into specs/functional.md"
|
||||
description: "Per resolved decision 3."
|
||||
implementation_plan: |
|
||||
Append solo-paneel-spec.md content as a new H2 section
|
||||
"Solo Panel" inside docs/specs/functional.md.
|
||||
git rm docs/specs/functional.md#solo-panel
|
||||
grep -rln "solo-paneel-spec" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|docs/solo-paneel-spec\.md|docs/specs/functional.md#solo-panel|g'
|
||||
commit: docs(split): merge solo-paneel-spec into specs/functional.md
|
||||
priority: 3
|
||||
|
||||
- title: "Merge md3-color-scheme.md into design/styling.md"
|
||||
description: "Per resolved decision 2."
|
||||
implementation_plan: |
|
||||
Append md3-color-scheme.md content as H2 sections inside
|
||||
docs/design/styling.md. Drop redundant intro paragraphs.
|
||||
git rm docs/design/styling.md
|
||||
grep -rln "md3-color-scheme" docs/ CLAUDE.md AGENTS.md README.md \
|
||||
| xargs sed -i '' 's|docs/design/md3-color-scheme\.md|docs/design/styling.md|g'
|
||||
commit: docs(split): merge md3-color-scheme into design/styling
|
||||
priority: 3
|
||||
|
||||
- slug: trim-orientation
|
||||
title: "Phase 5 — Trim CLAUDE.md and AGENTS.md"
|
||||
description: |
|
||||
Move conventions, branch/commit rules, MCP details, and deploy
|
||||
notes out of CLAUDE.md into runbooks/. Replace AGENTS.md with a
|
||||
10-line stub. Goal: CLAUDE.md ≤ 150 lines.
|
||||
acceptance_criteria: |
|
||||
- CLAUDE.md is at most 150 lines and contains only: scope,
|
||||
orientation pointers, hardstop rules, stack one-liner, pattern
|
||||
quickref, verification command. (See plan §5 for the
|
||||
skeleton.)
|
||||
- AGENTS.md is the 10-line stub from plan §7.
|
||||
- Removed sections live as their own files under docs/runbooks/.
|
||||
priority: 2
|
||||
tasks:
|
||||
|
||||
- title: "Extract Branch & Commit strategy → docs/runbooks/branch-and-commit.md"
|
||||
description: "CLAUDE.md §Branch & PR Strategy + §Commit Strategy + §Plan Mode."
|
||||
implementation_plan: |
|
||||
Move CLAUDE.md lines covering Branch & PR Strategy, Plan
|
||||
Mode, and Commit Strategy verbatim into
|
||||
docs/runbooks/branch-and-commit.md (with front-matter).
|
||||
In CLAUDE.md, leave a one-line link.
|
||||
commit: docs(trim): extract branch/commit rules into runbook
|
||||
priority: 2
|
||||
|
||||
- title: "Extract MCP integration → docs/runbooks/mcp-integration.md"
|
||||
description: "CLAUDE.md §MCP-integratie."
|
||||
implementation_plan: |
|
||||
Move §MCP-integratie verbatim. Replace in CLAUDE.md with a
|
||||
link + the bare list of tool names (no schemas).
|
||||
commit: docs(trim): extract MCP integration into runbook
|
||||
priority: 2
|
||||
|
||||
- title: "Extract Deployment → docs/runbooks/deploy-vercel.md"
|
||||
description: "CLAUDE.md §Deployment."
|
||||
implementation_plan: |
|
||||
Move §Deployment verbatim. Replace in CLAUDE.md with a link.
|
||||
commit: docs(trim): extract Vercel deployment into runbook
|
||||
priority: 2
|
||||
|
||||
- title: "Rewrite CLAUDE.md skeleton ≤ 150 lines"
|
||||
description: "Per plan §5 layout."
|
||||
implementation_plan: |
|
||||
Following plan §5, rewrite CLAUDE.md as:
|
||||
§1 What is Scrum4Me (2 sentences + README link)
|
||||
§2 Read first (INDEX, glossary)
|
||||
§3 How to find work (compact 2-track summary)
|
||||
§4 Hardstop rules (one line each, link to detail)
|
||||
§5 Stack one-liner per layer
|
||||
§6 Pattern quickref table (≤10 rows)
|
||||
§7 Verification command
|
||||
Verify: wc -l CLAUDE.md → ≤ 150
|
||||
commit: docs(trim): rewrite CLAUDE.md as ≤150-line skeleton
|
||||
priority: 2
|
||||
|
||||
- title: "Replace AGENTS.md with stub"
|
||||
description: "10-line redirect to CLAUDE.md per plan §7."
|
||||
implementation_plan: |
|
||||
Overwrite AGENTS.md with the stub from plan §7 (English).
|
||||
Verify no other doc references AGENTS.md for content
|
||||
(only as a name).
|
||||
commit: docs(trim): replace AGENTS.md with redirect stub
|
||||
priority: 3
|
||||
|
||||
- slug: adr-backfill
|
||||
title: "Phase 6 — Backfill ADRs for implicit decisions"
|
||||
description: |
|
||||
Write the actual ADR-0001 through ADR-0008 files. Scaffolding
|
||||
(templates, README, meta-ADR 0000) already exists from
|
||||
feat/docs-adr-and-index. Use Nygard for one-way-door decisions,
|
||||
MADR where rejected alternatives matter (auth, agent integration).
|
||||
acceptance_criteria: |
|
||||
- 8 new ADR files exist under docs/adr/ with correct numbering.
|
||||
- Each is status `accepted` and dated.
|
||||
- docs/adr/README.md table-of-contents lists all 8.
|
||||
- `npm run docs:index` shows them in the ADRs section.
|
||||
priority: 3
|
||||
tasks:
|
||||
|
||||
- title: "ADR-0001: base-ui-over-radix (Nygard)"
|
||||
description: "Why @base-ui/react instead of Radix."
|
||||
implementation_plan: |
|
||||
Copy docs/adr/templates/nygard.md → docs/adr/0001-base-ui-over-radix.md
|
||||
Context: shadcn/ui visually identical to Radix-based components,
|
||||
but @base-ui/react uses render-prop composition and TS-correct
|
||||
prop API. Radix asChild caused TS errors in our setup.
|
||||
Decision: We adopt @base-ui/react and never import from Radix.
|
||||
Consequences: positive — TS-clean composition; negative — agent
|
||||
must remember the render-prop pattern (not asChild).
|
||||
Update docs/adr/README.md TOC.
|
||||
commit: docs(adr): add 0001-base-ui-over-radix
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0002: float-sort-order (Nygard)"
|
||||
description: "Why float instead of integer for drag-and-drop ordering."
|
||||
implementation_plan: |
|
||||
See docs/patterns/sort-order.md for the existing pattern.
|
||||
Context: drag-and-drop reordering with N items — integer
|
||||
positions force a renumber on every reorder.
|
||||
Decision: Use float sort_order; insert between two items as
|
||||
the midpoint.
|
||||
Consequences: positive — O(1) inserts; negative — float
|
||||
precision drift requires periodic compaction (document
|
||||
when).
|
||||
commit: docs(adr): add 0002-float-sort-order
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0003: one-branch-per-milestone (MADR)"
|
||||
description: "Why milestones, not stories, get branches — and the cost driver."
|
||||
implementation_plan: |
|
||||
Use MADR (alternatives matter — Vercel cost driver explicit).
|
||||
Considered options: branch-per-story, branch-per-milestone,
|
||||
trunk-based.
|
||||
Decision: branch-per-milestone, push only after user-test.
|
||||
Decision drivers: Vercel Hobby preview-build cost; small team
|
||||
size; AI-driven dev flow.
|
||||
More information: revisit when Vercel Pro is on.
|
||||
commit: docs(adr): add 0003-one-branch-per-milestone
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0004: status-enum-mapping (Nygard)"
|
||||
description: "Why DB UPPER_SNAKE and API lowercase, plus the lib/task-status.ts mapper."
|
||||
implementation_plan: |
|
||||
Context: Prisma uses UPPER_SNAKE for enums; OpenAPI/REST
|
||||
clients expect lowercase.
|
||||
Decision: DB stays UPPER; API exposes lower; conversion
|
||||
exclusively via lib/task-status.ts mappers.
|
||||
Consequences: negative — anyone tempted to .toLowerCase()
|
||||
elsewhere breaks the contract; mitigated by lint rule.
|
||||
commit: docs(adr): add 0004-status-enum-mapping
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0005: iron-session-over-nextauth (MADR)"
|
||||
description: "Why iron-session — alternatives weighed."
|
||||
implementation_plan: |
|
||||
Use MADR.
|
||||
Considered options: NextAuth/Auth.js v5, Clerk, Supabase Auth,
|
||||
iron-session.
|
||||
Decision: iron-session.
|
||||
Drivers: full control over cookie shape; demo-user policy
|
||||
requires synchronous check; no third-party redirect chain.
|
||||
commit: docs(adr): add 0005-iron-session-over-nextauth
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0006: demo-user-three-layer-policy (Nygard)"
|
||||
description: "Why the same check exists in proxy + actions + UI."
|
||||
implementation_plan: |
|
||||
Context: demo-user must never write. Defense-in-depth across
|
||||
network, server, and UI layers.
|
||||
Decision: enforce in proxy.ts (network), every Server
|
||||
Action / Route Handler (server), and disabled buttons +
|
||||
DemoTooltip (UI).
|
||||
See: docs/architecture/auth-and-sessions.md (after Phase 4
|
||||
split) and ST-1110 plan.
|
||||
commit: docs(adr): add 0006-demo-user-three-layer-policy
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0007: claude-question-channel-design (MADR)"
|
||||
description: "How the agent ↔ user async channel works and why."
|
||||
implementation_plan: |
|
||||
Use MADR.
|
||||
Considered options: synchronous polling only, push via SSE,
|
||||
persistent claude_questions table + LISTEN/NOTIFY.
|
||||
Decision: persistent table + LISTEN/NOTIFY trigger.
|
||||
See: docs/patterns/claude-question-channel.md and M11 plan.
|
||||
commit: docs(adr): add 0007-claude-question-channel-design
|
||||
priority: 3
|
||||
|
||||
- title: "ADR-0008: agent-instructions-policy (Nygard, supersedes audit doc)"
|
||||
description: "Replaces docs/decisions/agent-instructions-history.md as a real ADR."
|
||||
implementation_plan: |
|
||||
Migrate the conclusions of docs/decisions/agent-instructions-history.md
|
||||
into an ADR.
|
||||
After accepted: mark history doc as superseded with a
|
||||
top-of-file note linking to ADR-0008.
|
||||
commit: docs(adr): add 0008-agent-instructions-policy
|
||||
priority: 3
|
||||
|
||||
- slug: glossary-and-husky
|
||||
title: "Phase 7 — Glossary + pre-commit hook for INDEX.md"
|
||||
description: |
|
||||
Write a glossary and wire the index generator into husky so
|
||||
INDEX.md never goes stale. The script itself already exists.
|
||||
acceptance_criteria: |
|
||||
- docs/glossary.md exists with entries for PBI, Story, Sprint,
|
||||
Solo, Todo, demo-token, MCP-job, agent worker, claude-question.
|
||||
- .husky/pre-commit runs `npm run docs:index` only when staged
|
||||
changes touch docs/**/*.md, then `git add docs/INDEX.md`.
|
||||
- README points to docs/INDEX.md and docs/glossary.md.
|
||||
priority: 3
|
||||
tasks:
|
||||
|
||||
- title: "Write docs/glossary.md"
|
||||
description: "Single-page domain-term reference."
|
||||
implementation_plan: |
|
||||
Front-matter: status active, audience [ai-agent, contributor],
|
||||
language en.
|
||||
Terms (alphabetical):
|
||||
demo-token, demo-user, MCP-job, PBI, Solo Panel, Sprint,
|
||||
Story, Task, Todo, agent worker, claude-question.
|
||||
Each term: 1-2 sentences + link to canonical doc.
|
||||
commit: docs(glossary): add docs/glossary.md
|
||||
priority: 3
|
||||
|
||||
- title: "Wire docs:index into husky pre-commit"
|
||||
description: "Avoid stale INDEX.md."
|
||||
implementation_plan: |
|
||||
Edit .husky/pre-commit:
|
||||
if git diff --cached --name-only | grep -q '^docs/.*\.md$'; then
|
||||
npm run docs:index
|
||||
git add docs/INDEX.md
|
||||
fi
|
||||
Verify with: stage a doc edit and run git commit --dry-run
|
||||
commit: chore(docs): regenerate INDEX.md in pre-commit hook
|
||||
priority: 3
|
||||
|
||||
- title: "Add INDEX + glossary pointer to README"
|
||||
description: "Mensbezoekers vinden dan ook het orientation-laagje."
|
||||
implementation_plan: |
|
||||
In README.md add a short section under "Architectuur (kort)":
|
||||
## Documentation
|
||||
- docs/INDEX.md — generated index of all docs
|
||||
- docs/glossary.md — domain terms
|
||||
- CLAUDE.md / AGENTS.md — agent instructions
|
||||
commit: docs(readme): link INDEX + glossary + agent instructions
|
||||
priority: 4
|
||||
|
||||
- slug: link-check
|
||||
title: "Phase 8 — Doc-link health check"
|
||||
description: |
|
||||
Add a small node script that walks docs/, finds every markdown
|
||||
link, and verifies the path (and anchor) exists. Wire into
|
||||
npm test or CI so a broken link blocks merge.
|
||||
acceptance_criteria: |
|
||||
- scripts/check-doc-links.mjs exists, pure Node, no deps.
|
||||
- It validates relative .md links and #anchors.
|
||||
- It prints a non-zero exit code on failures.
|
||||
- `npm run docs:check-links` is wired in package.json.
|
||||
- At least one CI step (vitest config or a separate npm script)
|
||||
runs it.
|
||||
- All current docs pass the check after the renames from
|
||||
Stories 2–4.
|
||||
priority: 3
|
||||
tasks:
|
||||
|
||||
- title: "Write scripts/check-doc-links.mjs"
|
||||
description: "Walk docs/, parse markdown links, validate."
|
||||
implementation_plan: |
|
||||
Pure Node 20.
|
||||
For each .md file:
|
||||
extract markdown links via regex /\[([^\]]+)\]\(([^)]+)\)/g
|
||||
skip http(s):// and mailto: links
|
||||
for each relative link:
|
||||
resolve against the file's directory
|
||||
check the path exists
|
||||
if the link includes #anchor:
|
||||
read the target file, check for a heading whose
|
||||
GitHub-style slug matches the anchor
|
||||
Print a table of failures; exit 1 if any.
|
||||
commit: feat(docs): add doc-link checker script
|
||||
priority: 3
|
||||
|
||||
- title: "Wire docs:check-links in package.json"
|
||||
description: "Plus a `docs` super-script that runs index + check together."
|
||||
implementation_plan: |
|
||||
Add to package.json scripts:
|
||||
"docs:check-links": "node scripts/check-doc-links.mjs",
|
||||
"docs": "npm run docs:index && npm run docs:check-links"
|
||||
commit: chore(docs): wire docs:check-links and docs npm scripts
|
||||
priority: 4
|
||||
|
||||
- title: "Add docs check to CI"
|
||||
description: "Block merge on broken links."
|
||||
implementation_plan: |
|
||||
Edit .github/workflows/<existing>.yml:
|
||||
after the lint+test step, add:
|
||||
- run: npm run docs:check-links
|
||||
commit: ci(docs): block merge on broken doc links
|
||||
priority: 3
|
||||
|
||||
- title: "Run + fix any reported broken links"
|
||||
description: "Final sweep across the whole tree."
|
||||
implementation_plan: |
|
||||
npm run docs:check-links
|
||||
For each reported broken link: fix in a single commit per
|
||||
file. If the target was renamed in Stories 2–4 but a link
|
||||
slipped through, that's a missed sed sweep — fix and update
|
||||
this story's notes.
|
||||
commit: docs(links): fix broken cross-references after restructure
|
||||
priority: 3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Executor notes
|
||||
|
||||
The executor reads the YAML graph above and calls, in order:
|
||||
|
||||
1. `mcp__scrum4me__create_pbi` with the `pbi.title`, `pbi.description`,
|
||||
`pbi.priority`, `pbi.product_id` (substituted from `REPLACE_ME`).
|
||||
Capture the returned `pbi_id`.
|
||||
2. For each story under `pbi.stories`:
|
||||
`mcp__scrum4me__create_story` with `pbi_id`, `story.title`,
|
||||
`story.description`, `story.acceptance_criteria`, `story.priority`.
|
||||
Capture the returned `story_id`.
|
||||
3. For each task under `story.tasks`:
|
||||
`mcp__scrum4me__create_task` with `story_id`, `task.title`,
|
||||
`task.description`, `task.implementation_plan`, `task.priority`.
|
||||
|
||||
`sort_order` is intentionally omitted everywhere — the MCP server
|
||||
auto-assigns `last + 1` within the priority group, which gives a stable
|
||||
order matching this file's reading order.
|
||||
|
||||
If any call fails, halt and surface the response — don't retry blindly,
|
||||
because a partial create leaves the graph half-built.
|
||||
|
||||
After a successful run: store the returned PBI/story/task IDs somewhere
|
||||
the executor can hand back, so a follow-up can verify everything
|
||||
exists and the totals match (1 PBI, 8 stories, 39 tasks).
|
||||
|
||||
---
|
||||
|
||||
## 6. Verification
|
||||
|
||||
- [x] Spec written.
|
||||
- [x] YAML graph parses cleanly with PyYAML; story/task counts verified
|
||||
(1 PBI, 8 stories, 39 tasks; phase distribution 7/5/4/3/5/8/3/4).
|
||||
- [ ] Executor runs end-to-end against the docker sandbox.
|
||||
- [ ] DB shows 1 PBI titled "Docs-restructure for AI-optimized lookup".
|
||||
- [ ] DB shows 8 stories under it.
|
||||
- [ ] DB shows 39 tasks across the 8 stories.
|
||||
- [ ] `mcp__scrum4me__get_claude_context` for the PBI returns the
|
||||
context block (section 1) verbatim as the description.
|
||||
|
|
@ -1,3 +1,12 @@
|
|||
---
|
||||
title: "Tweede Claude Agent — Planning Agent"
|
||||
status: proposal
|
||||
audience: [maintainer, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
applies_to: []
|
||||
---
|
||||
|
||||
# Plan: Tweede Claude Agent — Planning Agent (PBI/Story → children)
|
||||
|
||||
> **Eerder goedgekeurd plan in deze file:** *Scrum4Me v1.0 Release* (mobile shell + sprint-snapshots + release-discipline). Beschikbaar in chat-history; te verhuizen naar `docs/plans/v1-release.md` op een later moment. Dit nieuwe plan vervangt de plan-file inhoudelijk niet — het v1.0-werk blijft van kracht parallel hieraan.
|
||||
|
|
@ -150,7 +159,7 @@ Plaatsing:
|
|||
|
||||
**Live updates:** bestaande `useClaudeJobsStore` (Zustand, populated uit SSE) — alleen `kind` toevoegen aan filter-helpers.
|
||||
|
||||
### Stap 6 — MCP-tools (`scrum4me-mcp` repo, aparte PR)
|
||||
### Stap 6 — MCP-tools (`mcp` repo, aparte PR)
|
||||
|
||||
**Wijziging 1 — bestaande tool uitbreiden:**
|
||||
|
||||
|
|
@ -202,10 +211,10 @@ Korte prompt-flow:
|
|||
1. `wait_for_job({ accept_kinds: ['PLANNING'], wait_seconds: 600 })` — claim
|
||||
2. Lees `planning_target` uit response (PBI of STORY) + `existing_*`
|
||||
3. **Lees lokale docs uit Scrum4Me-checkout:**
|
||||
- `docs/functional.md` (functioneel kader)
|
||||
- `docs/specs/functional.md` (functioneel kader)
|
||||
- `docs/architecture.md` (technisch kader)
|
||||
- `docs/patterns/*.md` (relevante patterns op basis van target-titel/-beschrijving)
|
||||
- `docs/styling.md` als target UI-werk betreft
|
||||
- `docs/design/styling.md` als target UI-werk betreft
|
||||
4. Bedenk children:
|
||||
- Voor `STORY`-target: 3-7 taken met titel, korte beschrijving, `implementation_plan` (verwijst naar relevante patterns + bestanden), priority
|
||||
- Voor `PBI`-target: 2-5 stories met titel, beschrijving in user-story-format, acceptance_criteria, priority
|
||||
|
|
@ -227,7 +236,7 @@ Bij failure: `update_job_status({ status: 'FAILED', error })` + toast voor user.
|
|||
| Status-pill rendering per status | `__tests__/components/shared/planning-job-pill.test.tsx` |
|
||||
| Knop disabled-state in StoryDialog/PbiDialog bij actieve job | `__tests__/components/backlog/dialog-planning-button.test.tsx` |
|
||||
|
||||
MCP-tools testen in `scrum4me-mcp` repo (aparte PR).
|
||||
MCP-tools testen in `mcp` repo (aparte PR).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -252,16 +261,16 @@ MCP-tools testen in `scrum4me-mcp` repo (aparte PR).
|
|||
| `components/shared/planning-job-pill.tsx` | NEW | Generic pill-component |
|
||||
| `docs/patterns/claude-agent-roles.md` | NEW | Pattern-doc: één table, kind-enum, accept_kinds-arg, lokale agent-prompts |
|
||||
| `docs/architecture.md` | MODIFY | Sectie "Claude Agents" uitbreiden — twee rollen, schema, queue, prompts |
|
||||
| `docs/pbi-dialog.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
|
||||
| `docs/story-dialog.md` | MODIFY | Idem |
|
||||
| `docs/task-dialog.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
|
||||
| `docs/specs/dialogs/pbi.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
|
||||
| `docs/specs/dialogs/story.md` | MODIFY | Idem |
|
||||
| `docs/specs/dialogs/task.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
|
||||
| `__tests__/actions/claude-jobs-planning.test.ts` | NEW | |
|
||||
| `__tests__/lib/claude-job-status.test.ts` | MODIFY | `kind`-mapping testen |
|
||||
| `__tests__/api/realtime-solo-planning.test.ts` | NEW | |
|
||||
| `__tests__/components/shared/planning-job-pill.test.tsx` | NEW | |
|
||||
| `__tests__/components/backlog/dialog-planning-button.test.tsx` | NEW | |
|
||||
|
||||
### scrum4me-mcp repo (aparte PR, na Scrum4Me-merge)
|
||||
### mcp repo (aparte PR, na Scrum4Me-merge)
|
||||
|
||||
| File | Action |
|
||||
|---|---|
|
||||
|
|
@ -281,12 +290,12 @@ MCP-tools testen in `scrum4me-mcp` repo (aparte PR).
|
|||
4. **Status-pill component + tests** (Stap 5a) — losstaande primitive
|
||||
5. **Trigger-knoppen in StoryDialog + PbiDialog** (Stap 5b) — UI-trigger werkt, agent nog niet
|
||||
6. **Pause** — verifieer end-to-end met handmatig insert in `claude_jobs` (kind=PLANNING) of via mock-MCP-call
|
||||
7. **MCP-PR in scrum4me-mcp repo** (Stap 6) — `wait_for_job` uitbreiden, types updaten
|
||||
7. **MCP-PR in mcp repo** (Stap 6) — `wait_for_job` uitbreiden, types updaten
|
||||
8. **Lokaal `/generate-plan`-command schrijven + testen** (Stap 7) — agent claimt, leest, schrijft
|
||||
9. **End-to-end test** (Stap 8) — story → klik knop → agent rendert taken → SSE → live in TaskPanel
|
||||
10. **Docs-PR** — pattern-doc `claude-agent-roles.md`, architecture-update, dialog-profielen aanvullen
|
||||
|
||||
Branch-naming: `feat/M15-planning-agent` (Scrum4Me) + `feat/planning-agent` (scrum4me-mcp).
|
||||
Branch-naming: `feat/M15-planning-agent` (Scrum4Me) + `feat/planning-agent` (mcp).
|
||||
|
||||
Conform CLAUDE.md "branch-per-milestone": commits accumuleren lokaal, pushen pas na gebruikerstest.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue