adr-skill

Executable architecture decision records capture intent, constraints, implementation steps, and testable verification so agents can implement changes autonomously. A four-phase workflow scans code, captures intent, drafts from templates, and reviews with checklists to produce agent-ready documentation.

Bootstrapping an ADR directory and index initializes structured architecture decision tracking within a repository. The skill sets up the folder structure and maintains the index automatically as new decisions are proposed, accepted, rejected, deprecated, or superseded.

Managing the ADR lifecycle involves proposing, accepting, rejecting, deprecating, and superseding decisions while consulting existing records first. The workflow ensures index maintenance and encourages reviewing prior decisions before drafting new ones to avoid context re-litigation.

Simple ADR templates work for straightforward decisions, while MADR-style formats suit scenarios requiring detailed options and tradeoffs. The skill guides authors to choose the appropriate format based on how many alternatives and consequences must be recorded.

Architecture decision records designed for agentic coding include explicit implementation plans with affected file paths and checkbox-based verification criteria. This structure allows AI agents to execute changes and self-verify results without requiring follow-up human clarification.