From f233dd815ebf9586525e0acacfeb8ff450ee6919 Mon Sep 17 00:00:00 2001 From: Janpeter Visser <30029041+madhura68@users.noreply.github.com> Date: Fri, 8 May 2026 10:07:58 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20gap-fixes=20=E2=80=94=20adr?= =?UTF-8?q?/manual/architecture=20refs,=20npm=20run=20verify,=20MCP=20&=20?= =?UTF-8?q?cron=20sectie=20(#168)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Why: bij /init bleek CLAUDE.md ~95% accuraat maar miste verwijzingen naar docs/adr, docs/manual en docs/architecture; verify-command was incompleet (typecheck ontbrak); worker/job-systeem en cron-schedule waren niet zichtbaar zonder config-files te lezen. - Orientatie: 3 nieuwe pointers (adr/manual/architecture) - Hoe werk vinden + Verificatie + Deployment: `npm run verify && npm run build` - Stack: Vitest-rij toegevoegd - Hardstop: ClaudeJob queue lifecycle bullet - Patterns quickref: realtime-notify-payload, story-with-ui-component, web-push - Nieuwe sectie 'MCP & cron': externe MCP-server, cron-schedules, realtime-kanaal - Env vars: verwijzing naar VAPID/Sentry/Anthropic in .env.example - Frontmatter last_updated -> 2026-05-08 Co-authored-by: Claude Opus 4.7 (1M context) --- CLAUDE.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ea2dbb5..e368c38 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,7 @@ title: "CLAUDE.md — Scrum4Me" status: active audience: [ai-agent] language: nl -last_updated: 2026-05-03 +last_updated: 2026-05-08 --- # CLAUDE.md — Scrum4Me @@ -23,6 +23,9 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ | `docs/api/rest-contract.md` | REST API contract voor Claude Code | | `docs/design/styling.md` | **Lees vóór elk component** — MD3-tokens, shadcn | | `docs/plans/-*.md` | Implementatieplan per milestone | +| `docs/adr/` | Architecture Decision Records — tech-keuzes (base-ui vs Radix, sort-order, demo-policy, …) | +| `docs/manual/` | 7-delige gebruiks- en operationele handleiding (workflow, git, docker, troubleshooting) | +| `docs/architecture/` | 6 topische architecture-bestanden (data-model, auth, sprint-execution, …) — uitwerking van `docs/architecture.md` | --- @@ -33,7 +36,7 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ 2. `mcp__scrum4me__get_claude_context` → pak de next story 3. Voer taken uit in `sort_order`; update status per taak 4. Lees het relevante patroon en styling vóór je begint -5. Verifieer: `npm run lint && npm test && npm run build` +5. Verifieer: `npm run verify && npm run build` — `verify` = lint + typecheck + test 6. Commit per laag: `git add -A && git commit` — **geen** `git push` — zie [docs/runbooks/branch-and-commit.md](./docs/runbooks/branch-and-commit.md) 7. Herhaal stap 2–6 per story; branch blijft dezelfde 8. Queue leeg → `git push -u origin ` + `gh pr create` @@ -56,7 +59,8 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo - **Enum:** DB UPPER_SNAKE ↔ API lowercase — uitsluitend via `lib/task-status.ts` - **Foutcodes:** 400 = parse-fout, 422 = Zod-validatie, 403 = demo-token - **Server/client grens:** `*-server.ts` bevat DB/node-only; nooit importeren in client component -- **Deployment:** `npm run lint && npm test && npm run build` vóór elke PR. Selectieve deploy-controle (labels + path-filter): zie [docs/runbooks/deploy-control.md](./docs/runbooks/deploy-control.md) +- **Worker/jobs:** `ClaudeJob` queue (`QUEUED → CLAIMED → RUNNING → DONE|FAILED|SKIPPED`); MCP-worker claimt via `wait_for_job` en sluit met `update_job_status` — zie [worker-idempotency.md](./docs/runbooks/worker-idempotency.md) +- **Deployment:** `npm run verify && npm run build` vóór elke PR. Selectieve deploy-controle (labels + path-filter): zie [docs/runbooks/deploy-control.md](./docs/runbooks/deploy-control.md) --- @@ -70,6 +74,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo | State | Zustand + dnd-kit | | DB | Prisma v7 + PostgreSQL (Neon) | | Auth | iron-session + bcryptjs | +| Test | Vitest (`__tests__/`, config in `vitest.config.ts`) | | Utilities | Zod, Sonner, Sharp, Vercel Analytics | --- @@ -88,6 +93,9 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo | QR-pairing | `docs/patterns/qr-login.md` | | Claude ↔ user vraagkanaal | `docs/patterns/claude-question-channel.md` | | Entity Dialog (verplicht) | `docs/patterns/dialog.md` | +| Realtime NOTIFY-payload | `docs/patterns/realtime-notify-payload.md` | +| Story met UI-component | `docs/patterns/story-with-ui-component.md` | +| Web Push | `docs/patterns/web-push.md` | --- @@ -100,7 +108,17 @@ SESSION_SECRET="" # min 32 chars CRON_SECRET="" # Bearer-secret /api/cron/* ``` -Volledig schema: `lib/env.ts`. Canonieke lijst: `.env.example`. +Volledig schema: `lib/env.ts`. Canonieke lijst: `.env.example` — bevat ook web-push (`VAPID_*`, `INTERNAL_PUSH_SECRET`), Sentry (`SENTRY_*`) en optioneel `ANTHROPIC_API_KEY`. + +--- + +## MCP & cron + +- **MCP-server (extern):** standalone Node-proces in `~/Development/scrum4me-mcp/` — Prisma-schema gesynced via `sync-schema.sh`. 30+ tools (`get_claude_context`, `wait_for_job`, `update_task_status`, …) +- **Cron (vercel.json):** + - `/api/cron/expire-questions` — dagelijks 04:00 UTC + - `/api/cron/cleanup-agent-artifacts` — dagelijks 03:00 UTC +- **Realtime:** SSE op `/api/realtime/*`, gevoed door PostgreSQL `LISTEN`/`NOTIFY` op kanaal `scrum4me_changes` (vereist `DIRECT_URL` voor pooler-bypass) --- @@ -113,7 +131,7 @@ PBI (niet: Feature/Epic) · Story (niet: Ticket) · Sprint Goal (niet: Objective ## Verificatie ```bash -npm run lint && npm test && npm run build +npm run verify && npm run build # verify = lint + typecheck + test ``` Worker job-status protocol (wanneer `DONE` / `SKIPPED` / `FAILED`): zie [docs/runbooks/worker-idempotency.md](./docs/runbooks/worker-idempotency.md).