adr-new

/adr-new

What it does

Creates a new numbered ADR file in docs/adr/ and adds an entry to the index. ADRs are the lightweight memory of why the architecture looks the way it does — without them, six months from now nobody (human or agent) remembers why we chose A instead of B.

The convention is documented in [docs/adr/README.md](../../docs/adr/README.md): MADR-flavored, numbered, immutable status (proposed → accepted → deprecated / superseded).

Workflow

1. Find target dir. Default docs/adr/ from the current repo root

(via git rev-parse --show-toplevel). If no docs/adr/ exists, ask the user: "create it now?". If yes, also copy templates/adr-template.md if shipped (the plugin ships its own template under docs/adr/template.md — useful as a reference even when the target repo doesn't have one yet).

1. Pick next number. List existing docs/adr/NNNN-*.md files,

parse the leading number, take the max + 1. Pad to 4 digits.

1. Get the title.
2. If $ARGUMENTS has a positional, use it as the title.
3. If --noninteractive, fail if no title was given (we won't

hallucinate one).

• Otherwise, prompt the user.
• Convert to kebab-case for the filename:

0042-replace-polling-with-webhooks.md.

1. Ask for context (skip in --noninteractive):
2. One-line summary of the problem.
3. The chosen option (one sentence, stated as fact in present

tense).

• 1–3 alternatives considered (one line each).
• Whether to mark status: proposed (default) or accepted (if

the team already decided in conversation and just needs the record).

1. Generate the file at docs/adr/<NNNN>-<kebab-title>.md using

the MADR template (the plugin ships [docs/adr/template.md](../../docs/adr/template.md) for reference). Substitute:

• NNNN → resolved number
• Title → user-provided title
• YYYY-MM-DD → today (date +%Y-%m-%d)
• Status → resolved value
• Context / Decision / Alternatives → user input or

<TODO: fill in> placeholders if user skipped them

1. Update the index. Append the new ADR to the bulleted list in

docs/adr/README.md (or create it if it doesn't exist). Preserve the existing index style: - [NNNN — Title](NNNN-kebab.md)

1. Report. Print the new file path and remind the user that ADRs

are immutable once accepted — future revisions are new ADRs superseding the old one, not edits.

Hard rules

• Numbers are immutable. Once shipped, an ADR's number never

changes. If you regenerate the file (because of typos in the title before commit), keep the number.

• Status is immutable once accepted. Edits to an accepted ADR

should be limited to typos and link fixes. Substantive changes ship as a new ADR that explicitly supersedes the old one (Status: superseded by NNNN).

• The index is the source of truth for "what ADRs exist." Always

update it; never let it drift from the directory contents.

• Never overwrite an existing ADR. If the kebab-title collides

with an existing file, ask the user for a different title.

Tunables

• --status accepted — start the ADR as accepted rather than

proposed. Use when the decision is already settled and you're just recording it.

• --noninteractive — skip prompts; requires a title positional and

fills the context/decision/alternatives with <TODO> placeholders.

• --dry-run — print what would be written, write nothing.

When to write an ADR (and when not to)

Write an ADR for:

• Architectural tradeoffs likely to be re-litigated (e.g., "no

embedding RAG", "AGENTS.md canonical, CLAUDE.md import").

• Decisions that depend on external constraints (a vendor, an open

issue, a benchmark result).

• Decisions where alternatives are plausible enough that a future

agent will propose them.

Don't write an ADR for:

• Implementation choices the code itself shows (variable names,

function structure).

• One-off tactical fixes.
• Things covered by an obvious convention (test naming, lint config).

If you're not sure: write it. Three sentences in docs/adr/0042.md is cheap; re-arguing the same point six months later is expensive.

What this skill does NOT do

• Doesn't make the decision. It records a decision you've already

made. If you don't yet know the decision, you want a docs/specs/ document (or superpowers:brainstorming), not an ADR.

• Doesn't read the conversation context. You tell it the

decision in your own words; the skill just structures the file.

• Doesn't supersede or modify existing ADRs. Modification is a

manual edit + new ADR with Status: superseded by NNNN.