adr

Architecture decision records capture significant software design choices in a versioned, searchable document. Using the MADR format ensures each record includes frontmatter, required sections, pros and cons, and Mermaid diagrams, making governance and decision history consistent across teams.

You create a MADR file by invoking the Skill with a short description of your architectural decision. It automatically determines the next sequential ADR number, creates the docs/adrs/ directory, and writes a structured file containing frontmatter, required sections, pros and cons, and Mermaid diagrams.

Yes, you can enable team-based drafting by adding the --review flag when creating the architecture decision record. This engages a drafter agent and an architect agent to conduct a formal review, allowing your team to approve the decision before the MADR document is finalized.

Maintaining a sequential, standardized set of ADRs in MADR format provides a clear, versioned record of architectural decisions for onboarding engineers. Including required sections, pros and cons, and Mermaid diagrams in a dedicated docs/adrs/ directory makes decision history searchable and easy to understand.

No, you do not need to manually number your architecture decision records. The Skill automatically determines the next sequential ADR number and writes the properly structured MADR file into the docs/adrs/ directory, ensuring consistent numbering and governance without manual tracking.

Yes, Mermaid diagrams are a required part of the MADR format rules enforced during generation. When you create an architecture decision record, the Skill ensures inclusion of Mermaid diagrams alongside required sections, frontmatter, and pros and cons to visually communicate the design.