I’ve added an ADR plugin to my skills marketplace. It’s a single skill that gives the agent the tools to find, read, and author Architecture Decision Records using the Nygard template, with superseded and amended relationships so older decisions stay intact. I first built the skill as a wrapper around adr-tools but found it easier and more portable to hand the model the templates directly.
Alongside the tools, the skill tells the agent when to consult ADRs before planning and when to draft a new one.
Rationale
Mahdi Yusuf’s Why Your Coding Agent Keeps Undoing Your Architecture nudged me into building this. I hadn’t previously considered ADRs (or, really, guidance outside of guidance files) as a solution to that problem.
Shortcomings
It runs on model judgment. The skill says when to consult ADRs and when to write one, but the agent still has to recognize that the change in front of it is architectural rather than incidental and leverage the skill appropriately. I find that I have to point the model at the skill manually during planning to encourage the creation of an ADR.
Even when the agent does write one, the resulting ADRs often read like changelogs since models tend to favor documenting the implementation over capturing the decision. ADRs often need their own review session after they are written but before the code is implemented.