Architecture Decision Records (ADR)

Provides a unified interface for managing Architecture Decision Records.

Usage

/adr <ACTION> [ARGUMENTS]

Actions

• init [DIRECTORY] - Initialize ADR directory structure
• new <TITLE> - Create new ADR with given title
• supersede <NUMBER> <TITLE> - Create ADR that supersedes existing one
• list - List all ADRs in the project
• search <TERM> - Search ADRs by content
• view <NUMBER> - View specific ADR
• help - Show this help

What are ADRs?

Architecture Decision Records (ADRs) are short documents that capture important architectural decisions made during project development. They help teams:

• Record the context and reasoning behind decisions
• Track the evolution of architectural choices
• Onboard new team members
• Avoid revisiting already-settled decisions

ADR Structure

Each ADR typically contains:

• Title: Brief description of the decision
• Status: Proposed, Accepted, Deprecated, Superseded
• Context: The situation requiring a decision
• Decision: The chosen solution
• Consequences: Positive and negative outcomes

ADR Template

A template is available at $SKILL_PATH/templates/adr-template.md:

markdown
1# [NUMBER]. [TITLE]
2
3Date: [DATE]
4
5## Status
6
7[Proposed | Accepted | Deprecated | Superseded by [ADR-NUMBER]]
8
9## Context
10
11[Describe the context and problem statement]
12
13## Decision
14
15[Describe the decision and solution]
16
17## Consequences
18
19### Positive
20- [Positive outcome 1]
21- [Positive outcome 2]
22
23### Negative
24- [Negative outcome 1]
25- [Risk or trade-off]

ADR Directory Detection

Common ADR locations to check:

• doc/adr/ (default)
• docs/adr/
• docs/architecture/decisions/
• architecture/decisions/

Process Examples

Create new ADR:

bash
1/adr new "Use PostgreSQL for primary database"

List all ADRs:

bash
1/adr list

Search ADRs:

bash
1/adr search "database"

View specific ADR:

bash
1/adr view 5