jellydn/my-ai-tools/adr

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

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
• Mark settled decisions as final before moving on

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:

# [NUMBER]. [TITLE]
 
Date: [DATE]
 
## Status
 
[Proposed | Accepted | Deprecated | Superseded by [ADR-NUMBER]]
 
## Context
 
[Describe the context and problem statement]
 
## Decision
 
[Describe the decision and solution]
 
## Consequences
 
### Positive
 
-[Positive outcome 1]
-[Positive outcome 2]
 
### Negative
 
-[Negative outcome 1]
-[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:

/adr new "Use PostgreSQL for primary database"

List all ADRs:

/adr list

Search ADRs:

/adr search "database"

View specific ADR:

/adr view 5