| name | new-adr |
| description | Create a new MADR-style architectural decision record in fragments/adrs/. Use when the user asks to draft, write, add, record, or create a new ADR / decision record / architectural decision. Computes the next zero-padded NNN, writes the file with the canonical structure, and appends a row to the README index table. |
new-adr
Create a new architectural decision record in fragments/adrs/ and update the README index in one step.
When to use
Invoke when the user asks to create / draft / write / record an architectural decision. If the decision is already
described in the conversation, draft from that context. Otherwise ask one consolidated question for: title, the chosen
option, and a brief context — then proceed.
Procedure
- Compute the next number. List
fragments/adrs/, find the highest existing NNN_*.md, add one, zero-pad to three
digits. Numbers are never reused — even if a previous ADR was rejected or deleted, do not fill its slot.
- Derive the filename.
NNN_title_with_underscores.md — snake_case, ASCII only, drop punctuation.
- Default the metadata.
Status: Accepted and Date: = today's actual date (YYYY-MM-DD) unless the user says
otherwise. Other valid statuses: Proposed, Rejected, Deprecated, Superseded by [NNN](NNN_title.md).
- Write the file at
fragments/adrs/NNN_title_with_underscores.md using the canonical structure below. Include
### Consequences and ## More Information unless the user explicitly asks to omit them — both are optional but
usually present.
- Update the README index. Append a new row to the
| ADR | Date | Status | table under ## Decision records in
the repo-root README.md (i.e. ./README.md), linking to the new file.
- Format. Run
deno fmt fragments/adrs/<new-file>.md ./README.md.
- Report back with the new file path and a one-line note that the README index was updated.
Canonical ADR structure
Produce a file matching this shape (the leading # is the title, not a section break):
# {Short title — the solved problem and chosen solution}
**Status:** {Accepted | Proposed | Rejected | Deprecated | Superseded by [NNN](NNN_title.md)} | **Date:** {YYYY-MM-DD}
## Context and Problem Statement
{Two or three sentences. Make the scope of the decision explicit — point at the components/connectors involved.
Articulating it as a question is fine.}
## Considered Options
- {option 1}
- {option 2}
- ...
## Decision Outcome
Chosen option: "{...}", because {justification — the decisive criterion or the force it resolves}.
### Consequences
- Good, because {positive consequence}
- Bad, because {negative consequence}
- ...
## More Information
{Optional. Links to relevant code/docs, follow-up actions, or a Mermaid diagram. House style for diagrams uses
`config: { look: handDrawn }` to match the README. Diagrams may also sit inline above wherever they aid understanding.}
Conventions to honour
- ADRs are immutable once accepted — never edit a past ADR's substance. To change a decision, write a new ADR with
Status: Accepted whose body explains the change, and update the older ADR's status line to
Superseded by [NNN](NNN_title.md). Status updates and typo fixes are the only acceptable edits.
- Numbering is zero-padded and never reused.
- Filenames and directory names are snake_case (project-wide convention).
- Use the bold metadata line under the title (this repo's house style), not YAML frontmatter.
Out of scope
- Auto-rewriting a superseded ADR's status. If the new ADR supersedes an older one, mention the older ADR's number in
your report so the user can update it manually.
