Madhura68 8a7d419972 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.

2026-05-02 21:25:26 +00:00

3.6 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

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.

3.6 KiB Raw Blame History