adr-authoring

Document MADR-style Architecture Decision Records with required sections.

50|7|Updated Apr 18, 2026

Search Tags:#architecture #documentation #adr #software-engineering #madr #design-decisions #decision-record

Ready to run

npx skills add https://github.com/loiane/specs-driven-development-spring-angular --skill adr-authoring-loiane

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: adr-authoring
Source: https://github.com/loiane/specs-driven-development-spring-angular/tree/main/.windsurf/skills/adr-authoring
Command: npx skills add https://github.com/loiane/specs-driven-development-spring-angular --skill adr-authoring-loiane

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Author MADR-style Architecture Decision Records under .specs/<feature-id>/adr/. Use whenever a non-obvious technical decision is made, a default is overridden, or a waiver is granted.

Core Features & Use Cases

MADR-compliant ADRs live at .specs/<feature-id>/adr/NNN-<slug>.md with a zero-padded, unique number per feature.
Each ADR file contains the required MADR sections: Title, Status, Context, Decision drivers, Considered options, Decision outcome, Consequences, and Links.
File layout and governance ensure traceability of design decisions across features and lifecycles.

Quick Start

Create an ADR at .specs/<feature-id>/adr/NNN-<slug>.md following the MADR template.

Frequently Asked Questions about adr-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I document architectural decisions using MADR format?▼

To document architectural decisions using MADR format, create an ADR file at `.specs/<feature-id>/adr/NNN-<slug>.md` containing required sections: Title, Status, Context, Decision drivers, Considered options, Decision outcome, Consequences, and Links.

When should I write an architecture decision record?▼

You should write an architecture decision record whenever a non-obvious technical decision is made, a default configuration is overridden, a waiver is granted, or multiple design alternatives exist for a software engineering feature.

What sections are required in a MADR architecture decision record?▼

Required MADR architecture decision record sections include Title, Status, Context, Decision drivers, Considered options, Decision outcome, Consequences, and Links to ensure complete design rationale traceability across feature lifecycles.

What is the standard file layout for storing ADRs in a project?▼

The standard file layout for storing ADRs places files at `.specs/<feature-id>/adr/NNN-<slug>.md`, using a zero-padded, unique number per feature to maintain traceability of design decisions across the codebase.

Can I use this to override default software engineering configurations?▼

Yes, you can use this to document when default software engineering configurations are overridden by generating a MADR-compliant ADR that captures the specific context, decision drivers, and consequences of overriding the default.

Does this ADR format work without external dependencies?▼

Yes, this ADR authoring format works without external dependencies, using standard markdown files and a structured directory layout to capture design decisions and rationale directly within your software engineering project repository.