dotclaude

Command in documentation

adr

Write an Architecture Decision Record from the current discussion or a stated decision: numbers it in sequence under docs/adr/, captures context, the options considered with their trade-offs, the decision, and its consequences, in the adr-writing skill's format and the repo's existing ADR style if one exists. Use when a design choice has just been made in conversation, when a reviewer asks why something was done this way, or when a decision needs to outlive the people who made it.

Arguments
<decision title> [--supersedes N] [--status proposed|accepted]
Model
inherit
Allowed tools
Read, Write, Glob, Grep, Bash(git:*), Bash(ls:*), Bash(date:*)

Install

As a plugin

Bundled in the docs plugin. Add the marketplace once, then install the bundle; it updates with the marketplace.

/plugin marketplace add KhaledSaeed18/dotclaude
/plugin install docs@dotclaude

As a single item

Run from the project root; the command lands under .claude/. Copy it to ~/.claude/ to make it global.

npx shadcn@latest add KhaledSaeed18/dotclaude/adr

Files installed

  • .claude/commands/adr.md

What it does

Context

Title and options: $ARGUMENTS

Today: !date +%Y-%m-%d

Existing ADRs:

!ls docs/adr docs/decisions doc/adr adr 2>/dev/null | tail -15 || echo "(none; docs/adr/ will be created)"

Last ADR (for format):

!for d in docs/adr docs/decisions doc/adr adr; do f=$(ls $d/*.md 2>/dev/null | sort | tail -1); [ -n "$f" ] && sed -n 1,40p "$f" && break; done 2>/dev/null || echo "(no template to match; using the adr-writing format)"

Task

Write one ADR by applying the adr-writing skill.

  1. Locate the directory and the next number. Use the existing ADR directory if any; otherwise docs/adr/. Number is the highest existing plus one, four digits (0007). File name NNNN-<kebab-title>.md.
  2. Match the existing format if ADRs exist (headings, status vocabulary, metadata line). Otherwise use the skill's template.
  3. Fill it from the conversation. The context, options, and reasoning were usually just discussed; capture them faithfully, including the options that were rejected and why. Where the discussion did not cover something the template needs (consequences, migration), write what follows from the decision and mark speculation as such.
  4. Status from --status (default accepted if the decision was made, proposed if it is still open). With --supersedes N, set this ADR's "Supersedes" line and append "Superseded by NNNN" to the old one's status.
  5. Show the ADR before writing and ask for a yes. Then write it, and if the repository keeps an index (docs/adr/README.md or similar), add the row.

Report the path and a one-line summary. Do not commit; that is /commit.

This is the command as installed, rendered from its source on GitHub. Read it as Markdown.

  • adr-writingWrite Architecture Decision Records that a future engineer can act on: a numbered, immutable record with the context that forced the decision, the options...
  • openapi-specWrite, generate, or review an OpenAPI 3.1 specification for an HTTP API so that it is accurate to the implementation, complete for consumers (schemas...
  • readme-writingWrite or restructure a README that gets a reader from landing to first success in minutes: a one-line purpose, a working quick start verified against the...
  • technical-writingWrite and edit developer documentation, guides, design notes, and engineering blog posts with a working writer's discipline: audience and purpose first...