Create a new Architectural Decision Record (ADR). Use when recording an architectural decision, either standalone or linked to an accepted proposal. Handles numbering and cross-referencing. ADRs are immutable after acceptance except for the superseded_by field. Once all ADRs for a proposal are accepted, create a plan via `/new-plan --from-proposal NNN`.
Create a new ADR, either standalone or linked to an accepted proposal. In the pipeline, ADRs sit between proposals and plans: proposals define intent, ADRs record decisions, and plans implement them.
/new-adr <short-title> [--from-proposal NNN] [--module <path>] [--root]
| Argument | Required | Description |
|---|---|---|
<short-title> | Yes | Short, hyphenated title for the decision |
--from-proposal NNN | No | Link to an originating proposal (must be accepted) |
--module <path> | No |
| Target module path |
--root | No | Create at repo root level |
--from-proposal NNNParse arguments. Extract title, proposal number, and target.
Locate and verify the proposal. Find proposal NNN and verify its status is accepted. If not accepted, report: "Cannot link ADR to proposal NNN: proposal has status '<status>'. Only accepted proposals can be linked."
Get next sequence number. Run:
bash scripts/next-number.sh --dir <target-decisions-dir>
Create the ADR file. Read templates/decision.md and create <target>/NNN-<short-title>.md.
Populate frontmatter:
| Field | Value |
|---|---|
title | Derived from short title |
number | NNN from step 3 |
status | proposed |
author | Git user name or prompt |
created | Today's date |
originating_proposal | The proposal number |
superseded_by | null |
Pre-populate from proposal. Copy relevant context from the proposal to seed the ADR's Context section.
Identify related architecture docs that should reference this ADR once accepted.
--from-proposal (standalone)originating_proposal: null.After creating a new ADR, prompt the user:
"Does this ADR supersede an existing ADR? (enter number or skip)"
If the user provides a number:
superseded_by frontmatter field to the new ADR's number. (This is the one permitted mutation on an accepted ADR.)Once an ADR is accepted, it is immutable. The only permitted change is setting superseded_by when a new ADR supersedes it. To change a decision, create a new ADR.
templates/decision.md — ADR template (copy of scaffold/templates/core/decision.md)scripts/next-number.sh — Determines the next NNN sequence number