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: 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).

2. Pick next number. List existing docs/adr/NNNN-*.md files, parse the leading number, take the max + 1. Pad to 4 digits.

3. Get the title.

   • If $ARGUMENTS has a positional, use it as the title.
   • 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.

4. Ask for context (skip in --noninteractive):

   • One-line summary of the problem.
   • 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).

5. Generate the file at docs/adr/<NNNN>-<kebab-title>.md using the MADR template (the plugin ships 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

6. 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)

7. 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.