dark-madr 0.1.0

Architecture Decision Records management tool

dark-madr

A Python CLI for managing Architecture Decision Records.

Compatible with adr-tools workflow. Supports Nygard and MADR templates.

For background on ADRs, see the included paper: Using ADR on GitHub

Installation

pip install dark-madr

For development:

uv sync
uv pip install -e .

Usage

# Initialize ADR directory
adr init

# Create a new ADR
adr new "Use PostgreSQL for primary database"

# List all ADRs
adr list

# Show a specific ADR
adr show 1

# Supersede an existing ADR
adr new "Use PostgreSQL 15" --supersedes 1

# Generate table of contents
adr generate toc

Configuration

Configure defaults in pyproject.toml:

[tool.adr]
dir = "docs/decisions"
template = "madr"
default_status = "proposed"
default_authors = ["Architecture Team"]

Initialize configuration:

adr init-config
adr config  # view current settings

Commands

Command	Description
adr init	Initialize ADR directory with first ADR
adr new <title>	Create a new ADR
adr list	List all ADRs
adr show <number>	Display an ADR
adr generate toc	Generate table of contents
adr templates	List available templates
adr config	Show current configuration
adr init-config	Add config section to pyproject.toml

Options

adr new "Title" --template madr    # Use specific template
adr new "Title" --status accepted  # Set initial status
adr new "Title" --supersedes 3     # Supersede ADR-0003
adr --adr-dir ./docs list          # Override ADR directory

Templates

Two built-in templates:

• nygard (default) - Michael Nygard's original format
• madr - Markdown Any Decision Records format

View template structure:

adr help-template nygard
adr help-template madr

Custom templates can be added to a directory specified by template_dir in config.

Development

uv sync --all-extras
uv run pytest
uv run mypy src/
uv run ruff check src/

References

• Documenting Architecture Decisions - Michael Nygard
• Lightweight ADRs - ThoughtWorks Tech Radar (Adopt, Nov 2017)
• adr-tools - Nat Pryce
• MADR - Markdown Any Decision Records

License

MIT