---
title: Architecture Decision Records
status: active
audience: ai-agent, maintainer, contributor
language: en
last_updated: 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/`](./templates/). Default to Nygard.

### Nygard (default — [`templates/nygard.md`](./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`](./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](./0000-record-architecture-decisions.md) | Record architecture decisions | accepted | Nygard |
| [0001](./0001-base-ui-over-radix.md) | @base-ui/react over Radix UI | accepted | Nygard |
| [0002](./0002-float-sort-order.md) | Float sort_order for drag-and-drop reorder | accepted | Nygard |
| [0003](./0003-one-branch-per-milestone.md) | One branch per milestone (Hobby plan) | accepted | MADR |
| [0004](./0004-status-enum-mapping.md) | Status enum mapping via lib/task-status.ts | accepted | Nygard |
| [0005](./0005-iron-session-over-nextauth.md) | iron-session over NextAuth/Clerk | accepted | MADR |
| [0006](./0006-demo-user-three-layer-policy.md) | Demo-user three-layer write guard | accepted | Nygard |
| [0007](./0007-claude-question-channel-design.md) | Agent ↔ user question channel via persistent table + LISTEN/NOTIFY | accepted | MADR |
| [0008](./0008-agent-instructions-in-claude-md.md) | 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`](../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.