adr-tools

ADR Tools

Mechanics for working with npryce/adr-tools — the adr CLI that creates numbered Architecture Decision Records. Pairs with the adr-author agent: that agent decides whether an ADR is warranted and writes the prose; this skill drives the CLI correctly.

Pre-flight

command -v adr || echo "adr-tools not installed — see https://github.com/npryce/adr-tools"
cat .adr-dir 2>/dev/null   # project's configured ADR directory
ls "$(cat .adr-dir 2>/dev/null || echo docs/adr)/" 2>/dev/null | head -3

If the pre-flight reports adr missing, run /project-init to set up this repo's tooling — it installs the adr CLI as a capability tool (see its ${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/capability-tools.md) — or install it directly: see npryce/adr-tools (the CLI link is the fallback).

Project convention is docs/adr/. adr-tools stores the directory in .adr-dir at the project root — adr reads that file to find the ADRs no matter what subdirectory you're in. If .adr-dir is missing, run adr init docs/adr once. Do not init silently into a different path — confirm with the user if existing ADRs live somewhere unexpected.

Editor caveat — the most common failure

adr new opens $VISUAL or $EDITOR (defaulting to vi). In a Claude Code shell this hangs the command and exits non-zero — the file is created but empty. Two workarounds:

1. Preferred — bypass the editor. Run with a no-op editor, then write the body with the Write tool:

   EDITOR=true VISUAL=true adr new "<title>"
   

   The command prints the new file path to stdout. Read it, then replace the template Context/Decision/Consequences sections with the real content via Edit or Write.

2. Fallback — let it fail, then fill in. adr new "<title>" will create the templated file and exit non-zero from the editor failure. Read the new file (it lives at <adr-dir>/NNNN-<slugified-title>.md — typically docs/adr/) and fill it in.