Adds a 7-file English-language manual targeted at new human contributors:
index, overview, statuses & transitions (with mermaid state diagrams),
git workflow, MCP integration, docker, and troubleshooting. The manual
is the *map* — it cross-references existing runbooks/ADRs/architecture
docs rather than duplicating their content.
Regenerates docs/INDEX.md and validates with check-doc-links.mjs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
De drie relatieve `../../scrum4me-{mcp,docker}/...` paden in
docs/architecture/sprint-execution-modes.md verwezen naar zustere repos
buiten deze repo, waardoor `npm run docs:check-links` faalde. Vervangen
door absolute GitHub-URL's (de checker skipt `https://`-links), conform
de conventie in docs/runbooks/mcp-integration.md en docs/backlog/index.md.
- maybeCreateAutoPr → github.com/madhura68/scrum4me-mcp (main)
- scrum4me-mcp README → github.com/madhura68/scrum4me-mcp#readme
- scrum4me-docker CLAUDE.md → github.com/madhura68/scrum4me-docker (master)
Verificatie: `npm run docs:check-links` ✓ (97 files checked, 0 broken).
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Het advies-document dat als input diende voor PBI-50 is nu in docs/plans/
opgeborgen voor traceability. INDEX.md regenerated om hem op te nemen.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* PBI-50 F1: SPRINT_BATCH execution-strategy + cross-repo blocker + branch-resume
Schema-migratie + Scrum4Me-side wiring voor de nieuwe SPRINT_IMPLEMENTATION-flow:
- prisma: PrStrategy ADD VALUE 'SPRINT_BATCH'; ClaudeJobKind ADD VALUE
'SPRINT_IMPLEMENTATION'; nieuwe enum SprintTaskExecutionStatus; ClaudeJob.lease_until
+ status_lease_until index; SprintRun.previous_run_id (self-relation
SprintRunChain) voor branch-hergebruik bij resume; nieuwe sprint_task_executions
tabel met frozen plan_snapshot + verify_required_snapshot per task in scope.
- actions/sprint-runs.ts startSprintRunCore: nieuwe blocker-type 'task_cross_repo'
voor SPRINT_BATCH (pre-flight rejecteert sprints met cross-repo task_url).
Bij SPRINT_BATCH: één SPRINT_IMPLEMENTATION ClaudeJob (geen per-task loop).
- actions/sprint-runs.ts resumePausedSprintRunAction: SPRINT_BATCH-pad met
remaining-execution-check; bij onafgemaakt werk → nieuwe SprintRun met
previous_run_id + run.branch hergebruikt + nieuwe SPRINT_IMPLEMENTATION-job.
Oude SprintRun → CANCELLED. Bestaande PBI-49 P0 scope-DONE pad ongewijzigd.
- actions/products.ts updatePrStrategyAction: accepteert SPRINT_BATCH.
- components/products/pr-strategy-select.tsx: drie opties met helptekst,
gebruikt @prisma/client PrStrategy ipv lokaal type.
- components/sprint/sprint-run-controls.tsx: BLOCKER_LABELS + blockerHref
voor task_cross_repo.
Migratie applied op Neon. Type-check + 532 tests groen.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* PBI-50 F5: cross-repo blocker test voor SPRINT_BATCH
- task_cross_repo blocker fires bij task.repo_url ≠ product.repo_url
- happy path: tasks zonder repo_url-override of met match → één
SPRINT_IMPLEMENTATION-job (niet per-task).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* PBI-50 F5: docs/architecture/sprint-execution-modes.md
Vergelijking PER_TASK vs SPRINT_BATCH met trade-offs, datamodel-
toevoegingen (SprintTaskExecution, lease_until, SprintRunChain) en
MCP-tools-matrix per modus. Toegevoegd aan breadcrumb in
docs/architecture.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(cleanup): verwijder Todo's navlink en todo-referenties uit marketing page [cmotto5ia000nx3178lq6xk8d]
- nav-bar.tsx: Todo's navLink verwijderd; Ideas-link blijft staan
- app/page.tsx: /todos quick-access link, feature-entry en /api/todos API-doc verwijderd
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(cleanup): verwijder app/(app)/todos/ en components/todos/ [cmottjvzo000cx3172472cu4g]
* test(cleanup): verwijder POST /api/todos import en describe-block uit security.test.ts [cmotto5jn000px317kjqlba89]
- Import 'POST as postTodo' uit verwijderde todos-route verwijderd
- describe('POST /api/todos') sectie (3 tests) verwijderd
- 73 testfiles / 561 tests groen
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(cleanup): verwijder __tests__/api/todos.test.ts en __tests__/actions/todos-promote-idea.test.ts [cmottjw1u000fx317igq27mh5]
* feat(cleanup): verwijder actions/todos.ts en app/api/todos/route.ts; verplaats updateRolesAction naar actions/settings.ts [cmottjvy9000ax3173sgfjcqs]
* feat(db): migratie todos→ideas, counters bijwerken, todos dropt [cmotto5fh000jx317r7c5srvb]
Nieuwe Prisma-migratie die in één transactie actieve todos omzet naar
DRAFT-ideas met unieke IDEA-NNN codes, idea_code_counter per user
bijwerkt, en de todos-tabel dropt.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(schema): verwijder Todo model en relaties uit prisma/schema.prisma [cmottjvwu0008x317fwwodg3i]
* feat(cleanup): vervang open_todos door open_ideas in /api/products/:id/claude-context
Laatste prisma.todo-referentie verwijderd. Endpoint geeft nu open_ideas terug
(ideeën van de gebruiker voor dit product die niet gearchiveerd zijn en nog
niet status PLANNED hebben). Docs bijgewerkt in docs/api.md en
docs/api/rest-contract.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(landing): tour uitbreiden naar 6 screenshots incl. Ideas/Insights
Vervangt de oude 3 .jpg-screenshots door 6 nieuwe .png's met de huidige
visuele staat van de app. Volgorde toont de hele flow: ideeën binnen →
producten → backlog → sprint → solo → insights.
- Tour-array van 3 naar 6 figures, grid blijft lg:grid-cols-3 (2x2-rijen)
- Intro-tekst aangepast: "Zes weergaven van Scrum4Me — van inkomende
ideeën tot persoonlijk Kanban-bord en voortgangs-inzichten"
- Bestandsnamen gehernoemd naar lowercase-dash-conventie:
Sprint.png → sprint.png, Solo.png → solo.png, "Product Backlog.png" →
product-backlog.png, Producten.png → producten.png, Insights.png →
insights.png, Ideas-table.png → ideas-table.png,
Ideas-detail.png → ideas-detail.png (alleen voorbereiding, nog niet in
tour gebruikt)
- Oude .jpg-bestanden verwijderd
Niet onderdeel: hero/architectuur/handleiding-rewrite voor v3 — die staan
gepland onder ST-1224 en blijven open.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(landing): v3 — van idee tot pull request, met procesflow + Idea-laag
Verbreedt de landing-propositie van "executie lokaal" (v2) naar de
volledige cyclus idee → grill → plan → execute → PR. Eert M12 Ideas dat
sinds 2026-05-04 het kernconcept van het product is, plus auto-PR en
Sync-tab.
Hero:
- H1 "Van idee tot pull request — op je eigen hardware."
- Subhead benoemt grill→plan→materialise→agent→PR-cyclus en houdt het
lokaal-anker uit v2 vast.
Nieuw §3 "Van idee tot pull request":
- 4 procesflow-kaarten (Idee/Grill/Plan/Execute) met status-chips
(DRAFT/GRILLING/PLAN_READY/DONE→PR) en pijlen tussen kaarten op md+.
- Samenvattende paragraaf over state-machine, materializeIdeaPlanAction
en auto-PR.
Architectuur:
- docs/diagrams/architecture.mmd Worker-label uitgebreid met
"jobs: GRILL · PLAN · IMPL"; beide SVG's geregenereerd.
- Callout "Lokale worker" benoemt nu de drie jobsoorten expliciet.
Feature-grid (set D, 6 kaarten):
- Vervang "Hiërarchisch plannen" door "Ideas — Grill & Plan" op positie 1.
- Lokale Claude-agents: + auto-PR/SQUASH-merge zin.
- Realtime updates: + Sync-tab zin.
- Async vraagkanaal: + Grill-vragen zin.
Quickstart:
- Extra regel over UI-route (/ideas → Nieuw idee → Grill me) onder de
bestaande MCP-installatie code-block.
Scrum-samenvatting:
- Hiërarchie wordt twee-rij-systeem: Idea (DRAFT → GRILLED → PLAN_READY)
als bovenste rij, daaronder Product → PBI → Story → Taak met
"materialiseert ↓"-pijl.
- Terminologie krijgt 2 nieuwe tegels (Idea, Grill/Plan).
Handleiding (10 → 12 stappen):
- Nieuwe stappen 3-5 voor Idea-route (vastleggen, grillen, plan + materialiseren),
visueel gemarkeerd met tertiary-border en chip "Idea-route".
- Oude 7+8 (token + MCP-koppeling) samengevoegd tot stap 10.
- Stap 11 uitgebreid met Sync-tab-volgen.
- Stap 6 hernoemd "opbouwen" → "finetunen".
Plan-doc + grilling-context vastgelegd in docs/plans/landing-v3-idea-flow.md.
Tracked: ST-1224 onder PBI Marketing & Landingspagina.
Verified: lint 0 errors / 7 warnings (alle pre-existing), 564/564 tests,
productie-build slaagt.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Beschrijft hoe agent-jobs met Product.auto_pr=true automatisch
commit → push → PR → auto-merge → deploy doorlopen. Documenteert
welke laag wat doet (worker, scrum4me-mcp, GitHub Actions, Vercel),
setup-vereisten per product, foutpaden en wanneer auto_pr UIT
laten.
Onderdeel van PBI-36 ST-1220. De auto-PR-implementatie zelf zit
in scrum4me-mcp; deze runbook documenteert de bestaande flow plus
de nieuwe auto-merge-stap (scrum4me-mcp PR #23).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Beschrijft beslissingsboom verify_result × diff-staat × branch-staat
→ JobStatus, met SKIPPED gereserveerd voor al-gemergd werk en FAILED
voor échte fouten. Plus StoryLog-verplichting (log_implementation,
log_commit, log_test_result) en idempotency-protocol vóór schrijven.
PBI-33 batch (5-5 22:22) gedocumenteerd als case-study: drie
protocol-overtredingen die deze runbook + de nieuwe SKIPPED-status
aanpakken.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- lib/job-status.ts: SKIPPED ↔ 'skipped' mapping in beide richtingen
- components/shared/job-status.ts: label "Overgeslagen" + neutrale italic styling
- actions/admin/jobs.ts: cancel-guard erkent SKIPPED als eindstatus
- app/api/cron/cleanup-agent-artifacts: SKIPPED ook opruimen na 7d
- lib/insights/agent-throughput: SKIPPED telt mee als terminal
ACTIVE_JOB_STATUSES bewust ongewijzigd — SKIPPED is afgerond.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/backlog/index.md:
- New M12 row in milestone-overview
- Full M12 section with 10 stories (8 done, ST-1197 extern + ST-1201 in
progress); each story lists its task IDs
docs/runbooks/mcp-integration.md:
- wait_for_job payload contract documented per kind discriminator
(TASK_IMPLEMENTATION vs IDEA_GRILL vs IDEA_MAKE_PLAN)
- Per-kind agent behavior table
- 5 new MCP-tools documented: get_idea_context, update_idea_grill_md,
update_idea_plan_md, log_idea_decision; plus extended ask_user_question
contract (story_id|idea_id xor)
- Batch-loop step 2 expanded to switch on kind
docs/INDEX.md auto-regenerated (83 docs).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add FAQ subsection explaining that stories within the same batch don't
conflict (linear commits on shared branch), while parallel batches may
require rebase or serial PRs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- new enums IdeaStatus, ClaudeJobKind, IdeaLogType
- new models Idea (with @@unique([user_id, code]) + pbi_id @unique) and IdeaLog
- User.idea_code_counter Int @default(0) for IDEA-{nnn} code generation
- ClaudeJob.task_id nullable; new idea_id + kind fields + index
- ClaudeQuestion.story_id nullable; new idea_id field + index
- existing call sites narrowed to story-questions / task-jobs (idea-paths come in T-502+)
- includes the M12 plan doc copied from /Users/janpetervisser/.claude/plans
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/runbooks/v1-smoke-test.md (NIEUW): 11-secties handmatige checklist
voor de v1.0-pre-launch verificatie — auth, mobile UA-redirect, happy-path
flow, mobile shell, edit-flows, demo-policy, rate-limiting steekproef,
realtime, debug-routes 404 in productie, Lighthouse a11y per pagina,
rollback-trigger.
v1-readiness.md: 4 Before-launch items afgevinkt (demo-policy, privacy,
README, CHANGELOG); smoke-test verwijst nu naar de checklist; PWA-test
en v1.0.0-bump zijn de twee resterende handmatige items.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vier config-files volgens Next.js 15+ conventie:
- instrumentation.ts (root) → koppelt server/edge config aan runtime-hook
- instrumentation-client.ts → client-init + onRouterTransitionStart
- sentry.server.config.ts → node-runtime
- sentry.edge.config.ts → edge-runtime (proxy.ts)
next.config.ts gewrapped met withSentryConfig:
- Source-map-upload ALLEEN als SENTRY_AUTH_TOKEN gezet is
- Tunnel /monitoring omzeilt ad-blockers (*.sentry.io)
- Silent buiten CI
SDK is no-op zonder NEXT_PUBLIC_SENTRY_DSN — geen network/overhead in
dev of bij ontbrekende creds. Sample-rates conservatief: errors 100%,
performance 10% in productie / 100% in dev. Geen Replay (privacy-review
nodig + overkill voor MVP). sendDefaultPii uit.
.env.example gedocumenteerd; architectuur-doc bijgewerkt met nieuwe
sleutelbeslissing en file-tree-aanvulling. v1-readiness #1 verschoven
naar 'done', #2 hiermee in flight.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Acceptatiecriteria vroeg om 'flow per scherm' beschrijving in de
Mobile shell sectie. Toegevoegd: stap-voor-stap flow voor Settings,
Backlog en Solo schermen.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Living document onder docs/plans/v1-readiness.md. Vier secties (Now/Next/
Before launch/Later) met concrete actions voor de stap van v0.9.0 → v1.0.0.
Now-kandidaten:
- Edit-icoon op Product (todo cmoq3ox51 — UI-gat)
- Sentry/error-monitoring
- Rate-limiting op alle mutation-endpoints
- Accessibility-audit (Lighthouse a11y >=95)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vorige planlocatie (~/.claude/plans/twinkly-plotting-wombat.md) was overschreven
met ST-1209-plan; deze doc neemt het over.
Drie aanbevelingen verwerkt na evaluatie tegen huidige codebase:
- A. Gedeelde entityDialogContentClasses muteren (dekt ST-1133 + ST-1138 in één edit)
- B. Eigen route group app/(mobile)/ — nested layout kan parent-NavBar niet onderdrukken
- C. Gescheiden SplitPane cookie-key voor mobile (backlog-3-mobile)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
§ 4a beschrijft hybrid detail+inline-edit dialogen met dynamische
footer en blur-save: bv. TaskDetailDialog. Maakt expliciet wanneer je
deze variant kiest, welke § 4-eisen blijven gelden en welke vervallen
(geen dirty-guard, geen Cmd+Enter, geen full-record schema).
Profiel docs/specs/dialogs/task-detail.md verwijst nu naar § 4a en
documenteert de layout-keuzes (sticky header, scrollable body,
flex-wrap footer met job-status, plan-textarea max-h-[40vh]).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Aparte 'Entity codes' sectie legt uit dat PBI/Story/Task elk een
verplichte code hebben (max 30 chars, regex), per-product uniek,
stabiel bij re-parenting, met auto-generatie als POST-body de
code weglaat. Voorbeeld response in /next-story en /sprint/tasks
gebruikt nu T-42 i.p.v. ST-356.1 voor task-code.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Pbi.code en Story.code worden NOT NULL (tot dusver optional)
- Task krijgt code String + product_id String denorm + @@unique([product_id, code])
- Product krijgt back-relation tasks Task[]
- Migratie backfillt bestaande NULL-rijen via PL/pgSQL:
PBI-N (per product), ST-N (3-digit padded met GREATEST om
truncatie van LPAD bij 4-digit nummers te voorkomen),
T-N voor alle tasks
- Codes zijn stabiele identifiers (Jira-stijl flat-per-product),
zodat re-parenting de code niet muteert
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Story 5 van PBI "Alle dialogen conform docs/patterns/dialog.md".
- lib/schemas/sprint.ts — gedeelde zod-schemas (create/dates/goal)
- actions/sprints.ts — code+fieldErrors voor 422; code: 403 voor
auth/demo errors
- StartSprintButton dialog: useDirtyCloseGuard, useDialogSubmitShortcut,
entityDialog* layout-classes; DemoTooltip op trigger; veld-niveau
errors via fieldErrors
- SprintHeader's date- en complete-dialogen: zelfde behandeling; date-
dialog krijgt dirty-guard, complete-dialog krijgt DemoTooltip op
bevestigen
- docs/specs/dialogs/sprint.md — entity-profile dat alle drie de modes
documenteert; consolidatie naar één SprintDialog component bewust
uitgesteld
- Sprint-dates tests aangepast aan nieuwe action-shape
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reframe the landing page around what makes Scrum4Me unique: code execution
stays on the developer's own hardware (laptop, NAS or VM). The Vercel UI and
Neon DB are a metadata coordination layer; source code never leaves the local
worker. Adds a mermaid-rendered architecture diagram (two-zone: Scrum4Me-stack
vs Jouw kant) with light/dark variants generated via mmdc.
Page changes (app/page.tsx):
- Hero: H1 "Plannen in de cloud. Uitvoeren op je eigen machine." + new
subhead; CTA "Hoe het werkt" replaces "Demo bekijken" (anchors to
#architectuur).
- New section §3 "Architectuur" with light/dark SVG and 4 callout-cards
(Vercel · Neon · Lokale worker · GitHub) honestly describing what each
component stores or runs.
- Feature grid: 6 cards (set C) — combines Sprint Board + Solo Paneel,
adds Lokale Claude-agents, Realtime updates, Async vraagkanaal, Todo's.
LIVE callout removed (folded into Realtime card).
- "Twee manieren"-section replaced by a Quickstart with concrete git-clone
snippet for the MCP-server.
- Handleiding: 9 → 10 steps; MCP recommended in step 8; new step 9
"Story laten uitvoeren" describing the Voer-uit / job-queue flow;
step 1 mentions QR-pairing as alternative login.
- Footer: adds link to madhura68/scrum4me-mcp alongside the app repo.
Tooling:
- New docs/diagrams/architecture.mmd (mermaid source).
- New npm script "diagrams" generates light + dark SVG via mmdc; output
committed to public/diagrams/. No prebuild hook (manual regenerate, like
prisma generate / docs:index).
- Plan + grilling outcomes captured in docs/plans/landing-local-first.md.
Tracked under Scrum4Me story cmoq2qoik0001qa175iynfnaa
(PBI Marketing & Landingspagina, cmoq2q50s0000qa174rmrjove).
Verified: npm run lint (0 new errors), npm test (379/379), npm run build OK.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bundelt vier valkuilen in de huidige agent-flow: PBI-ordering,
schema-conflicten bij parallelle migraties, branch-naam-collisies via
8-char suffix, cross-product orchestratie. Eerste is al gedekt door de
merge-policy PBI; de andere drie zijn entries onder anchor-PBI
"Agent-flow: openstaande beslissingen" (prio 4).
Lokaal commit; PR pas wanneer er meer aanverwante docs-changes zijn.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bevestigt het huidige datamodel (Product.repo_url is single) en kiest "duplicate-PBI per product" voor cross-repo werk; markeert een Initiative-laag (boven PBI) als toekomstige uitbreiding zodra de duplicatie-pijn te groot wordt.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* 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>
* docs(naming): drop scrum4me- prefix from doc filenames
Rename 10 docs/scrum4me-*.md files to unprefixed kebab-case names.
Update every internal link in docs/, CLAUDE.md, AGENTS.md, README.md.
* docs(naming): lowercase API.md and MD3 filenames
Rename docs/API.md → docs/api.md and
docs/MD3_Color_Scheme_Documentation.md → docs/md3-color-scheme.md.
Update all internal links across 7 files.
* docs(naming): rename plan file to kebab-case ASCII
Rename "docs/plans/Tweede Claude Agent — Planning Agent.md"
→ docs/plans/tweede-claude-agent-planning.md. No external links needed updating.
* docs(naming): rename middleware.md to proxy.md (next 16)
docs/patterns/middleware.md → docs/patterns/proxy.md following
the Next.js 16 proxy.ts rename. Update link in CLAUDE.md.
* docs(naming): polish CLAUDE.md doc-index after renames
Fix doubled scrum4me-scrum4me-mcp repo references (cascade from
prior sed) in CLAUDE.md, docs/architecture.md, backlog.md,
agent-instruction-audit.md, and plans/ST-1109. Update
'Middleware' label to 'Proxy middleware' in patterns table.
