Scrum4Me/docs/adr

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.