/adr

name: adr
description: "Record architecture decisions with ADRs — captures why, alternatives considered, and consequences"
license: MIT
compatibility: cline, claude, opencode, amp, codex, gemini, cursor, pi
hint: Use when managing architecture decisions, creating ADRs, or tracking architectural choices
user-invocable: true
metadata:
  audience: all
  workflow: documentation

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