From 30f9b1afe718470f96fdfe076768f2ab66d196d2 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 00:37:42 +0200 Subject: [PATCH] docs(naming): polish CLAUDE.md doc-index after renames --- AGENTS.md | 2 +- CLAUDE.md | 10 +++++----- README.md | 2 +- docs/agent-instruction-audit.md | 10 +++++----- docs/architecture.md | 2 +- docs/backlog.md | 2 +- docs/plans/M10-qr-pairing-login.md | 2 +- docs/plans/ST-1109-pbi-status.md | 2 +- .../archive/2026-04-27-claude-md-workflow-update.md | 6 +++--- docs/plans/docs-restructure-ai-lookup.md | 4 ++-- docs/plans/docs-restructure-pbi-spec.md | 2 +- docs/plans/tweede-claude-agent-planning.md | 2 +- 12 files changed, 23 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1f9f198..33224f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ Read `CLAUDE.md` and the relevant files in `docs/` before changing behavior. The When changing behavior, API responses, dependencies, environment variables, deployment behavior, or analytics, update the matching docs in the same change: - `README.md` for setup, dependencies, deployment, and API overview. -- `docs/functional-spec.md` for user-facing/API requirements. +- `docs/functional.md` for user-facing/API requirements. - `docs/architecture.md` for stack, access model, data model, env vars, and deployment. - `docs/patterns/` when a reusable implementation rule changes. - `CLAUDE.md` and this file when an agent instruction would have prevented the issue. diff --git a/CLAUDE.md b/CLAUDE.md index 715e09e..42f98d6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over | Document | Gebruik voor | |---|---| -| `docs/functional-spec.md` | Acceptatiecriteria, randgevallen, user flows | +| `docs/functional.md` | Acceptatiecriteria, randgevallen, user flows | | `docs/architecture.md` | Stack, datamodel, Prisma schema, Zustand stores | | `docs/backlog.md` | Welke task bouwen, volgorde, "done when"-criteria | | `docs/personas.md` | Lars (primair), Dina, Remi — gebruik bij UI-beslissingen | @@ -33,7 +33,7 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over | `docs/styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen | | `docs/agent-instruction-audit.md` | Waarom de agent-instructies zijn aangescherpt; checklist voor toekomstige wijzigingen | | `docs/plans/-*.md` | Implementatieplan per milestone — Bestanden, Stappen, Aandachtspunten, Verificatie. Lees vóór je aan een ST begint. Milestone-key matcht backlog-header (`M9`, `M3.5`, `PBI-9`, …). | -| [`madhura68/mcp`](https://github.com/madhura68/mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule | +| [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule | --- @@ -60,7 +60,7 @@ Werken aan een task kan via twee tracks. Track A heeft de voorkeur als je in Cla ### Track B — manueel (Codex of zonder MCP) 1. Lees de task in `backlog.md` -2. Zoek de bijbehorende feature-spec in `functional-spec.md` +2. Zoek de bijbehorende feature-spec in `functional.md` 3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/styling.md` als dat van toepassing is 4. Bouw — test — verifieer de "Done when"-criteria 5. Vraag of de code correct is @@ -116,7 +116,7 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven. | Route Handler (REST API) | `docs/patterns/route-handler.md` | | Zustand optimistische update + rollback | `docs/patterns/zustand-optimistic.md` | | Float sort_order drag-and-drop | `docs/patterns/sort-order.md` | -| Middleware (route protection) | `docs/patterns/proxy.md` | +| Proxy (route protection) | `docs/patterns/proxy.md` | | QR-pairing (unauth-SSE + pre-auth cookie) | `docs/patterns/qr-login.md` | | Bidirectionele async-comms MCP-agent ↔ user | `docs/patterns/claude-question-channel.md` | | **Entity Dialog (verplicht voor élke create/edit/detail-dialog)** | `docs/patterns/dialog.md` — bron-of-truth; per entiteit één profile-doc (bv. `docs/task-dialog.md`) | @@ -269,7 +269,7 @@ docs(ST-XXX): document profile feature ## MCP-integratie -Scrum4Me heeft een eigen MCP-server in repo [`madhura68/mcp`](https://github.com/madhura68/mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd. +Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd. ### Tools beschikbaar in Claude Code (18) diff --git a/README.md b/README.md index 944608f..a24dc15 100644 --- a/README.md +++ b/README.md @@ -279,7 +279,7 @@ De productieomgeving is gericht op Vercel + Neon. ### Documentatie -- [Functionele specificatie](docs/functional-spec.md) +- [Functionele specificatie](docs/functional.md) - [Technische architectuur](docs/architecture.md) - [Backlog](docs/backlog.md) - [Agent-instructie audit](docs/agent-instruction-audit.md) diff --git a/docs/agent-instruction-audit.md b/docs/agent-instruction-audit.md index 556b373..ca9eb0f 100644 --- a/docs/agent-instruction-audit.md +++ b/docs/agent-instruction-audit.md @@ -26,7 +26,7 @@ Dit document legt vast welke wijzigingen zijn gecontroleerd, welke documentatie | Reorder-acties valideren alle IDs binnen de juiste parent-scope | `actions/stories.ts`, `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `docs/patterns/sort-order.md`, `CLAUDE.md`, `AGENTS.md` | | Sprint afronden accepteert alleen stories uit de actieve sprint | `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `AGENTS.md` | | Todo-promotie gebruikt scoped todo lookup en `pbi.product_id` als bron van waarheid | `actions/todos.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `CLAUDE.md`, `AGENTS.md` | -| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/functional-spec.md`, `docs/backlog.md`, `docs/patterns/route-handler.md` | +| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/functional.md`, `docs/backlog.md`, `docs/patterns/route-handler.md` | | `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` | | Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` | | `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/architecture.md` | @@ -52,7 +52,7 @@ Concrete regels: Een codewijziging is niet klaar als de documentatie een oud contract beschrijft. Agents moeten bij elke wijziging nagaan of deze plekken geraakt worden: - `README.md`: setup, scripts, dependencies, deployment, API-overzicht. -- `docs/functional-spec.md`: functionele eisen en API-contracten. +- `docs/functional.md`: functionele eisen en API-contracten. - `docs/architecture.md`: stack, datamodel, securitymodel, env vars, deployment. - `docs/backlog.md`: "done when"-criteria en scope van backlog-items. - `docs/patterns/`: herbruikbare implementatiepatronen. @@ -110,7 +110,7 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow - **ST-512** REST API uitgebreid met `code`, `description`, `implementation_plan` in alle endpoints - **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/api.md` - **PR #2 Codex-review-saga** — 8 testbestanden faalden bij de contract-flip; tests werden niet meebijgewerkt. Twee P2-issues van Codex: malformed JSON moet `400` blijven (P2.1), en `status: review` werd geaccepteerd terwijl de sprint-UI er niet mee om kan gaan (P2.2) -- **M7: mcp** — aparte MCP-server repo (`madhura68/mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule +- **M7: mcp** — aparte MCP-server repo (`madhura68/scrum4me-mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule - **lib/code.ts vs lib/code-server.ts** — gesplitst om client-bundle vrij te houden van `pg` (gaf eerst `Module not found: 'dns'` build-error) - **Wekelijkse schema-drift cron** (`trig_015FFUnxjz9WMuhhWNGBQKFD`) — remote agent die ma 08:00 Amsterdam de MCP-submodule syncet en typecheckt @@ -124,7 +124,7 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow | Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/backlog.md` (ST-511) | | `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/api.md` | | Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/api.md`, `CLAUDE.md` | -| MCP-server gepubliceerd als aparte repo | `madhura68/mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog.md` (M7) | +| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog.md` (M7) | ## Nieuwe preventieve regels @@ -169,7 +169,7 @@ De wekelijkse cron doet dit automatisch, maar ad-hoc checken is nog steeds verst `CLAUDE.md` is uitgebreid met: -- Specificatiedocumenten-rij voor `madhura68/mcp` +- Specificatiedocumenten-rij voor `madhura68/scrum4me-mcp` - Dual-track workflow (Track A: MCP-prompt; Track B: manueel) - Twee patroon-rijen: `lib/task-status.ts` en client/server module-boundary - Vier nieuwe conventies: entity codes in commits, lowercase API-status, error-code split, test-pariteit diff --git a/docs/architecture.md b/docs/architecture.md index 7c18ead..338bbbd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1194,7 +1194,7 @@ De bestaande `notify_task_change`-trigger op `tasks` vuurt automatisch de pg_not ### Hybride-ready -De huidige implementatie verwacht een lokale Claude Code-sessie die `wait_for_job` aanroept vanuit `madhura68/mcp`. Toekomstige uitbreiding naar Vercel Sandbox (serverless agent) vereist alleen een nieuw claim-endpoint — het datamodel en SSE-flow zijn ongewijzigd. +De huidige implementatie verwacht een lokale Claude Code-sessie die `wait_for_job` aanroept vanuit `madhura68/scrum4me-mcp`. Toekomstige uitbreiding naar Vercel Sandbox (serverless agent) vereist alleen een nieuw claim-endpoint — het datamodel en SSE-flow zijn ongewijzigd. ## Environment variables diff --git a/docs/backlog.md b/docs/backlog.md index 9667972..08ad818 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -481,7 +481,7 @@ De MVP is klaar wanneer Lars — de primaire persona — de volledige cyclus kan ### M7: MCP-server voor Claude Code -Aparte repo: [`madhura68/mcp`](https://github.com/madhura68/mcp). Native Prisma-toegang (geen REST-tussenlaag), stdio-transport, Scrum4Me-schema gevendord als git submodule. Tokens hergebruikt uit `api_tokens`. v1 is alleen dev-flow tools — geen PBI/sprint-creatie of profielbeheer. +Aparte repo: [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp). Native Prisma-toegang (geen REST-tussenlaag), stdio-transport, Scrum4Me-schema gevendord als git submodule. Tokens hergebruikt uit `api_tokens`. v1 is alleen dev-flow tools — geen PBI/sprint-creatie of profielbeheer. - [x] **ST-701** Repo-skeleton mcp - npm init, tsconfig strict, .gitignore, MCP SDK 1.29, Prisma 7, zod, tsx; lege `src/index.ts` die op stdio start diff --git a/docs/plans/M10-qr-pairing-login.md b/docs/plans/M10-qr-pairing-login.md index f56981c..13e70d3 100644 --- a/docs/plans/M10-qr-pairing-login.md +++ b/docs/plans/M10-qr-pairing-login.md @@ -17,7 +17,7 @@ Inloggen op een (publieke) desktop zonder wachtwoord: desktop toont QR, telefoon - 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-spec.md § F-01b](../functional-spec.md#f-01b-inloggen-via-mobiel-qr-pairing). +Functional spec: zie [functional.md § F-01b](../functional.md#f-01b-inloggen-via-mobiel-qr-pairing). **Implementatie-volgorde** (commit-strategy uit CLAUDE.md): diff --git a/docs/plans/ST-1109-pbi-status.md b/docs/plans/ST-1109-pbi-status.md index 19cfc4c..6b160b5 100644 --- a/docs/plans/ST-1109-pbi-status.md +++ b/docs/plans/ST-1109-pbi-status.md @@ -74,7 +74,7 @@ const pbiIdsToMarkDone = candidatePbis ## Opvolgactie buiten deze repo -[`madhura68/mcp`](https://github.com/madhura68/mcp): de `create_pbi` tool kan straks optioneel `status` accepteren. Submodule (`vendor/scrum4me`) moet gesynced worden na merge zodat de drift-bewaking maandag groen blijft. +[`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp): de `create_pbi` tool kan straks optioneel `status` accepteren. Submodule (`vendor/scrum4me`) moet gesynced worden na merge zodat de drift-bewaking maandag groen blijft. ## Verificatie (end-to-end) diff --git a/docs/plans/archive/2026-04-27-claude-md-workflow-update.md b/docs/plans/archive/2026-04-27-claude-md-workflow-update.md index a164577..e9c642d 100644 --- a/docs/plans/archive/2026-04-27-claude-md-workflow-update.md +++ b/docs/plans/archive/2026-04-27-claude-md-workflow-update.md @@ -45,7 +45,7 @@ Voeg toe onder de bestaande tabel: | Document | Gebruik voor | |---|---| -| `https://github.com/madhura68/mcp` | MCP-server repo: tools, prompts, schema-sync workflow | +| `https://github.com/madhura68/scrum4me-mcp` | MCP-server repo: tools, prompts, schema-sync workflow | (`docs/api.md` staat er al — laten staan.) @@ -93,7 +93,7 @@ Korte sectie (~15 regels): ```markdown ## MCP-integratie -Scrum4Me heeft een eigen MCP-server (repo: `madhura68/mcp`) +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 @@ -140,7 +140,7 @@ Voeg een sectie aan `docs/agent-instruction-audit.md` toe (datum: 2026-04-27) me ## Wat het NIET oplost - `AGENTS.md` (Codex) blijft achter; los aan te pakken indien gewenst -- Eventuele drift in `docs/functional-spec.md` rond status-enums — niet onderzocht; te volgen bij volgende audit +- Eventuele drift in `docs/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 diff --git a/docs/plans/docs-restructure-ai-lookup.md b/docs/plans/docs-restructure-ai-lookup.md index c40e6ea..ab640c4 100644 --- a/docs/plans/docs-restructure-ai-lookup.md +++ b/docs/plans/docs-restructure-ai-lookup.md @@ -61,7 +61,7 @@ Bij elke turn die met `CLAUDE.md` start, wordt minimaal 340 regels orientation i | Bestand | Regels | Waar het thuishoort | |---|---:|---| | `architecture.md` | 1.247 | `docs/architecture/` — splitsen (zie §4) | -| `functional-spec.md` | 650 | `docs/specs/functional.md` | +| `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` | @@ -148,7 +148,7 @@ In volgorde van belangrijkheid: │ │ └── project-structure.md (uit §Projectstructuur) │ │ │ ├── specs/ -│ │ ├── functional.md (huidige functional-spec.md) +│ │ ├── functional.md (huidige functional.md) │ │ ├── personas.md │ │ ├── solo-panel.md │ │ └── dialogs/ diff --git a/docs/plans/docs-restructure-pbi-spec.md b/docs/plans/docs-restructure-pbi-spec.md index c9dd61f..b8d9612 100644 --- a/docs/plans/docs-restructure-pbi-spec.md +++ b/docs/plans/docs-restructure-pbi-spec.md @@ -268,7 +268,7 @@ pbi: implementation_plan: | git mv docs/architecture.md docs/architecture.md git mv docs/backlog.md docs/backlog.md - git mv docs/functional-spec.md docs/functional.md + git mv docs/functional.md docs/functional.md git mv docs/pbi-dialog.md docs/pbi-dialog.md git mv docs/personas.md docs/personas.md git mv docs/product-backlog.md docs/product-backlog.md diff --git a/docs/plans/tweede-claude-agent-planning.md b/docs/plans/tweede-claude-agent-planning.md index 106c9e6..6052bd9 100644 --- a/docs/plans/tweede-claude-agent-planning.md +++ b/docs/plans/tweede-claude-agent-planning.md @@ -211,7 +211,7 @@ 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-spec.md` (functioneel kader) + - `docs/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