# ADR-0001 — Every change starts with an approved ADR (/docs/maintain/adr/ADR-0001-adr-driven-development-workflow)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Reworded by:** [ADR-0038](./ADR-0038-earlier-names-leave-the-pages-and-the-github-link-follows-the-move.mdx) (earlier names only)
- **Design documents:** `AGENTS.md` §2–§3, `content/docs/maintain/adr/index.mdx`, `content/docs/maintain/_templates/adr.mdx`

## Context [#context]

This repository is greenfield: a Fumadocs scaffold that will document every package,
library and project its owner builds — npm, Composer and other ecosystems, public and private
projects. The owner builds it change by change, largely with AI agents.

Two forces make an explicit gate necessary:

- **The expensive mistakes are structural and early.** How content is laid out per ecosystem
  and package, how versions are handled, and how private project documentation is kept off the
  public site are cheap to get right on paper and expensive to change once many pages and
  inbound links depend on them. A private page that was published cannot be unpublished.
- **Agents produce plausible work fast.** Without a gate, a decision is made implicitly in code
  and found late.

## Decision [#decision]

1. **Every feature and functional change starts with an ADR** in `content/docs/maintain/adr/`, written from
   `content/docs/maintain/_templates/adr.mdx`, with `Status: Proposed` and an index row in `content/docs/maintain/adr/index.mdx`.
2. **No application code is written until the owner explicitly approves it.** Approval sets
   `Status: Approved`, `Approved by`, `Approved on`.
3. **Once approved, the whole scope is implemented in one pass**, with tests and every affected
   document, without stopping for per-step review.
4. **Agents never commit, push, rebase or switch branches.** The owner reviews the working tree
   and commits.
5. **An approved ADR's Decision is never edited**; it is superseded by a new ADR.
6. **Content within approved conventions needs no ADR.** Writing or updating a package's or
   project's pages is the site's normal work; deciding the conventions themselves is not.

What needs an ADR is the table in `AGENTS.md` §2. Anything that decides how private project
documentation is stored, built, served or searched always does.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — ADR gate for every functional change | Decisions are explicit, reviewable and recorded; structural mistakes are caught before code | Ceremony on small features | Chosen |
| B — Code first, document after | Fast | Decisions are implicit; privacy and structure errors are found late | Rejected |
| C — ADRs only for "big" changes | Less ceremony | "Big" is judged by whoever wants to skip it | Rejected |

## Consequences [#consequences]

**Positive**

- Every decision has a record of why, which an agent in a later session can read.
- The owner controls scope change by change.

**Negative / accepted trade-offs**

- Small features carry an ADR's overhead. Accepted: the template keeps a small ADR small.

## Content invariants [#content-invariants]

Establishes the gate through which any departure from `AGENTS.md` §6 must pass.

## Security considerations [#security-considerations]

None directly — this is a process decision. It does make every later security decision pass
through the mandatory security section of an ADR (ADR-0005).

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §2–§3 describe the gate and execution rules.
- [x] `content/docs/maintain/adr/index.mdx` holds the index and the next free number.
- [x] `content/docs/maintain/_templates/adr.mdx` exists.
- Tests: not applicable (process only).

> Written together with the documents it governs, at the owner's direct request, so the
> implementation notes above are already done. If the owner rejects or changes this ADR, the
> documents are changed to match.

## Docs to update on implementation [#docs-to-update-on-implementation]

- [x] `content/docs/maintain/adr/index.mdx` — status on approval.