A general-purpose toolkit for managing Architecture Decision Records (ADRs) across multiple projects.

• Config-driven: Global defaults with project-specific overrides
• Extensible metadata: Support for project-specific metadata fields
• Validation: Automatic validation of ADR format and duplicate detection
• Search: Tag-based, content, and status search across ADRs
• Cross-project analysis: Detect duplicates across multiple repositories
• Clojure ecosystem: Built with Babashka, configured with EDN

1. Clone this repository to ~/.adr:

   git clone <repo-url> ~/.adr

2. Add ~/.adr/bin to your PATH:

   # For bash
   echo 'export PATH="$HOME/.adr/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   
   # For zsh
   echo 'export PATH="$HOME/.adr/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

3. Verify installation:

   adr-validate --help

Default configuration for all projects:

{:adr
 {:path "doc/adr"                          ; Default ADR location
  :template "~/.adr/template/default.md"   ; Default template
  :excluded-files #{"README.md"}           ; Files to skip
  :template-file "00000-template.md"       ; Template filename
  :metadata-schema :standard               ; Base schema
  :require-runnotes false}}                ; RunNotes optional

Override defaults per project:

{:adr
 {:path "docs/architecture/decisions"      ; Custom ADR path
  :require-runnotes true                   ; Require RunNotes field
  :accepted-duplicates #{"00029" "00030"}  ; Known duplicates

  ;; Optional: Extend metadata schema
  :metadata-extensions
  {:runnotes {:spec :adr/runnotes
              :required true}
   :custom-field {:spec :project/custom
                  :required false}}}}

All commands automatically discover your project root (via git) and load the appropriate configuration.

Check all ADRs for format compliance and duplicate sequence numbers:

# In project directory
cd ~/projects/my-app
adr-validate

# CI mode (minimal output)
adr-validate --ci

# Pre-commit hook (check staged files only)
adr-validate --check-new

# GitHub Actions (check PR files)
adr-validate --check-pr origin/main

Output:

📋 ADR Validation Report
========================

✅ No unexpected duplicate sequence numbers found

📊 Summary: 25 ADRs checked, 0 errors

Search by tag, content, or status:

# List all ADRs
adr-search list

# Search by tag
adr-search tag architecture
adr-search tag ui

# Search by content
adr-search content "state management"
adr-search content polylith

# Search by status
adr-search status Accepted
adr-search status Proposed

# List all tags
adr-search list-tags

# Show tag usage statistics
adr-search tag-summary

Example output:

00001-polylith-architecture.md
  Title: Polylith Architecture for Multi-Project Support
  Status: accepted
  Tags: :architecture :tooling :process

Scan multiple projects for duplicate ADR sequence numbers:

# Scan current project
adr-duplicate-detector

# Scan multiple projects
adr-duplicate-detector ~/projects/app1 ~/projects/app2

# Filter by category
adr-duplicate-detector --category critical ~/projects/*

# Ignore specific sequences
adr-duplicate-detector -i 00029,00030,00031

# Verbose output
adr-duplicate-detector -v ~/projects/*

ADRs use markdown with embedded EDN metadata:

# 00042 - Use Event Sourcing for Audit Log

\`\`\`edn :metadata
{:date "2025-10-01"
 :status :accepted
 :tag #{:architecture :audit :event-sourcing}}
\`\`\`

## Context

We need a reliable audit trail for all system changes...

## Decision

We will use event sourcing for the audit log...

## Consequences

### Positive
- Complete audit history
- Time-travel debugging

### Negative
- Increased storage requirements
- More complex queries

## Links
- [Related ADR](00041-cqrs-pattern.md)

Required (standard schema):

• :date - Creation date (YYYY-MM-DD)
• :status - :proposed, :accepted, :deprecated, or :superseded
• :tag - Set of keyword tags (e.g., #{:architecture :testing})

Optional (standard schema):

• :updated - Last update date
• :runnotes - Set of RunNotes references

Project-specific: Projects can define additional fields via :metadata-extensions in .adr.edn.

~/.adr/                  # Installation directory
├── bin/                # Executable scripts
│   ├── adr-validate
│   ├── adr-search
│   └── adr-duplicate-detector
├── template/           # ADR templates
│   └── default.md
├── config.edn          # Global configuration
├── plan.md             # Migration plan
└── README.md           # This file

~/.lib/                  # Shared libraries
├── adr-core.bb         # Config and path resolution
├── metadata-parser.bb  # EDN metadata parsing
└── adr-metadata-extractor.bb  # Metadata extraction

1. Initialize ADR directory:

   mkdir -p doc/adr
   cp ~/.adr/template/default.md doc/adr/00000-template.md

2. Create first ADR:

   # Copy template and edit
   cp doc/adr/00000-template.md doc/adr/00001-initial-architecture.md

3. Validate:

   adr-validate

1. Create .adr.edn in project root:

   {:adr
    {:path "docs/architecture/decisions"}}

2. Tools automatically use custom path:

   adr-validate  # Uses docs/architecture/decisions
   adr-search list

Prevent commits with duplicate ADR sequences:

# .git/hooks/pre-commit
#!/bin/bash
adr-validate --check-new

- name: Validate ADRs
  run: |
    adr-validate --check-pr origin/${{ github.base_ref }}

validate-adrs:
  script:
    - adr-validate --ci

Project structure:

my-app/
├── doc/
│   └── adr/
│       ├── 00000-template.md
│       └── 00001-use-postgres.md
└── src/

Usage:

cd my-app
adr-validate
adr-search list

No .adr.edn needed—uses global defaults.

Project structure:

enterprise-app/
├── .adr.edn
├── docs/
│   └── architecture/
│       └── decisions/
│           ├── 00000-template.md
│           └── 00001-microservices.md

.adr.edn:

{:adr
 {:path "docs/architecture/decisions"
  :require-runnotes true}}

Usage:

cd enterprise-app
adr-validate  # Uses custom path, requires :runnotes field

Scan multiple related repositories:

# Detect duplicates across microservices
adr-duplicate-detector \
  ~/projects/auth-service \
  ~/projects/user-service \
  ~/projects/payment-service

# Filter for critical issues only
adr-duplicate-detector --category critical ~/projects/*

Problem: Project config file has invalid EDN.

Solution:

# Validate EDN syntax
bb -e "(clojure.edn/read-string (slurp \".adr.edn\"))"

Problem: ADR directory doesn't exist or path is wrong.

Solution:

1. Check config:

   cat .adr.edn

2. Verify directory exists:

   ls -la doc/adr  # or custom path

Problem: ADR metadata is incomplete.

Solution: Ensure all required fields are present:

{:date "2025-10-01"
 :status :accepted
 :tag #{:architecture}}

Smoke tests verify core functionality:

# Run smoke test suite
~/.adr/test/smoke-test.bb

# Expected: 9 tests pass

Tests validate:

• Config files and templates exist
• All commands have working --help

Manual testing in projects:

cd ~/src/<project>
adr-validate
adr-search list

cd ~/.adr
clj-kondo --lint bin/* test/*
# Expected: 0 errors, 0 warnings

1. Create script in ~/.adr/bin/
2. Make executable: chmod +x ~/.adr/bin/new-script
3. Load shared libraries:

   (load-file (str (fs/expand-home "~/.lib/adr-core.bb")))

This toolkit includes comprehensive documentation for both human users and AI agents:

• README.md (this file) - Installation, configuration, usage, and examples
• Template - ADR template with detailed guidance

• CLAUDE.md - Quick reference and navigation guide for AI agents
• doc/README-PHILOSOPHY.md - ADR philosophy and design principles
• doc/README-WORKFLOWS.md - Detailed workflows for creating, validating, and searching ADRs
• doc/README-FILE-FORMAT.md - Complete file format and metadata specifications
• doc/README-INTEGRATION.md - Integration patterns with Requirements, RunNotes, and other tools
• doc/README-QUALITY.md - Quality enforcement, red flags, and common pitfalls

The modular documentation structure follows the DRY principle—each document is self-contained and loaded on-demand when needed, minimizing context overhead for AI agents while maintaining comprehensive coverage.

Contributions welcome! This toolkit is designed to be general-purpose while supporting project-specific needs through configuration.

MIT

• Nygard, M. (2011). Documenting Architecture Decisions. Cognitect Blog.
• ADR-00035: Folder and Script Naming Conventions
• Architecture Decision Records
• Babashka