📋 ADR Automation CLI

A CLI tool that scaffolds Architecture Decision Records from a template, enforces a consistent format across repos, and generates a browsable decision log.

Architecture Decision Records are one of the highest-leverage practices a team can adopt, yet most teams either skip them or write them inconsistently because there's no tooling to make it easy. The idea is a CLI — something like adr new "Switch from REST to gRPC for internal services" — that scaffolds a new ADR with a consistent structure: context, decision, consequences, status, and stakeholders.

Beyond scaffolding, the tool would enforce conventions through a lint step in CI: checking that required sections are present, that each ADR links to related decisions, and that superseded records are marked appropriately. Over time, this produces an auditable, navigable decision log that new team members can read to understand why the system is shaped the way it is, not just what it looks like.

The more interesting layer is a static site generator that converts the ADR markdown files into a browsable decision log — filterable by status, date, or tag, with backlinks between related decisions. Government and regulated-industry teams often have audit requirements around architectural rationale; a versioned, machine-readable decision log would satisfy many of those requirements out of the box. Keeping it simple — plain markdown in git — means no additional infrastructure and maximum longevity.