Stats
Actions
Tags
From principled-docs
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`.
How this skill is triggered — by the user, by Claude, or both
Slash command
/principled-docs:new-adrThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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 numbernpx claudepluginhub alexnodeland/principled --plugin principled-docsCreates Architecture Decision Records (ADRs) with title, status, and MADR/basic/extended templates. Auto-numbers sequentially, prompts for context/options/rationale, writes to docs/decisions/ or docs/adr/.
Creates a numbered MADR ADR in `docs/adr/` documenting load-bearing architectural decisions (database, framework, auth model, integration choice). Prompts for context, decision, and alternatives, then updates the index.