Janpeter Visser 7e45bbdbc0

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>

2026-05-03 03:21:59 +02:00

4.5 KiB

Raw Blame History

title	status	audience	language	last_updated
Architecture Decision Records	active	ai-agent, maintainer, contributor	en	2026-05-02

Architecture Decision Records

This directory contains the Architecture Decision Records (ADRs) for Scrum4Me.

What is an ADR

An ADR is a short document that captures a single significant architectural decision: the context that forced the decision, the choice we made, and the consequences of that choice. ADRs are immutable once accepted — if a later decision changes course, we write a new ADR that supersedes the old one.

We use ADRs because the project mixes several non-obvious choices (Next.js 16 specifics, @base-ui/react over Radix, float sort_order for drag-and-drop, iron-session over NextAuth, demo-user three-layer policy, MCP integration patterns) and an AI agent reading the codebase six months from now needs to find the why without spelunking through commit history.

File naming

NNNN-kebab-case-title.md

NNNN — four-digit zero-padded sequential number, starting at 0001 (0000 is reserved for the meta-ADR that introduces the practice).
kebab-case-title — lowercase, hyphen-separated, short noun phrase echoing the decision (base-ui-over-radix, not decided-to-use-baseui).
Always .md.

Choosing a template

Two templates live in templates/. Default to Nygard.

Nygard (default — `templates/nygard.md`)

Use Nygard for the common case: a decision that is essentially a one-way door with a clear motivating context and one obvious choice. Four sections: Title, Status, Context, Decision, Consequences (Positive / Negative).

Aim: ≤60 lines. Reads in under a minute.

MADR v4 (when alternatives matter — `templates/madr.md`)

Use MADR when the decision involves weighing multiple alternatives that a future reader would otherwise re-litigate. Triggers:

Authentication / session strategy (NextAuth vs iron-session vs Clerk).
Queue / messaging mechanics (LISTEN/NOTIFY vs Redis vs SQS).
Agent integration patterns (REST polling vs MCP vs SSE channel).
Schema or data-model choices with non-trivial migration cost.
Any decision where you want to record the rejected options so future contributors don't propose them again.

MADR adds: YAML front-matter (status, date, decision-makers, consulted, informed), explicit Decision Drivers, Considered Options, Pros and Cons of each option, Confirmation, and More Information.

Status lifecycle

proposed  →  accepted  →  (optionally) superseded by NNNN
                       ↘  (optionally) deprecated

proposed — drafted, awaiting decision-maker sign-off.
accepted — current binding decision; the codebase reflects this.
superseded by ADR-NNNN — replaced. Keep the file; never edit the Decision section. Add a one-line "Superseded by …" note at the top of the Status section and link to the new ADR.
deprecated — still current but no longer recommended; usually a precursor to a future supersession.

Once an ADR is accepted, it is immutable except for the Status field and typo fixes. Course corrections always create a new ADR.

Index of ADRs

#	Title	Status	Template
0000	Record architecture decisions	accepted	Nygard
0001	@base-ui/react over Radix UI	accepted	Nygard
0002	Float sort_order for drag-and-drop reorder	accepted	Nygard
0003	One branch per milestone (Hobby plan)	accepted	MADR
0004	Status enum mapping via lib/task-status.ts	accepted	Nygard
0005	iron-session over NextAuth/Clerk	accepted	MADR
0006	Demo-user three-layer write guard	accepted	Nygard
0007	Agent ↔ user question channel via persistent table + LISTEN/NOTIFY	accepted	MADR
0008	Agent instructions in CLAUDE.md + topical runbooks	accepted	Nygard

When new ADRs are added, the docs index generator (npm run docs:index) will list them in ../INDEX.md. Update this table by hand when you add or supersede an ADR — the script aggregates across the whole docs tree, this README is the canonical ADR-only roster.

4.5 KiB Raw Blame History