Adr Integration

ADR Integration

This skill provides guidance on integrating ADRs with CI/CD pipelines, documentation sites, and other development tools for automated workflows and better discoverability.

CI/CD Integration

GitHub Actions

name: ADR Checks

on:
  pull_request:
    paths:
      - 'docs/adr/**'

jobs:
  adr-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check ADR format
        run: |
          # Verify ADR numbering
          # Check required sections
          # Validate links

      - name: Update ADR index
        run: |
          # Regenerate README.md
          # Check for changes

GitLab CI

adr-validation:
  stage: lint
  rules:
    - changes:
        - docs/adr/**
  script:
    - ./scripts/validate-adrs.sh
    - ./scripts/update-adr-index.sh

Pre-commit Hooks

repos:
  - repo: local
    hooks:
      - id: adr-lint
        name: Lint ADRs
        entry: ./scripts/lint-adr.sh
        language: script
        files: ^docs/adr/.*\.md$

Documentation Site Integration

MkDocs

nav:
  - Home: index.md
  - Architecture:
    - Overview: architecture/overview.md
    - Decision Records: architecture/adr/README.md

plugins:
  - search
  - macros:
      module_name: adr_macros

Docusaurus

module.exports = {
  docs: {
    sidebar: {
      Architecture: [
        'architecture/overview',
        {
          type: 'category',
          label: 'Decision Records',
          items: ['architecture/adr/README'],
        },
      ],
    },
  },
};

Sphinx

.. toctree::
   :maxdepth: 2
   :caption: Architecture

   architecture/overview
   architecture/adr/index

Export Formats

HTML Export

Generate standalone HTML:

Apply CSS styling
Include navigation
Add status badges
Generate table of contents

JSON Export

Export for tooling integration:

{
  "adrs": [
    {
      "id": "0001",
      "title": "Use PostgreSQL",
      "status": "accepted",
      "date": "2025-01-15",
      "file": "docs/adr/0001-use-postgresql.md",
      "supersedes": [],
      "superseded_by": null,
      "related": ["0003", "0007"]
    }
  ],
  "stats": {
    "total": 25,
    "accepted": 20,
    "proposed": 3,
    "deprecated": 1,
    "superseded": 1
  }
}

PDF Export

Generate PDFs for:

Stakeholder presentations
Audit documentation
Offline reading
Compliance records

Tool Integrations

Jira/Issue Trackers

Link ADRs to tickets:

Create “ADR” issue type
Link implementation tickets to ADRs
Track ADR lifecycle in workflow

Confluence/Wiki

Sync ADRs to wiki:

Auto-publish accepted ADRs
Include cross-links
Maintain version history

Slack/Teams

ADR notifications:

New ADR proposed
ADR accepted/rejected
Compliance violations

Architecture Tools

Export to architecture tools:

C4 model diagrams
Enterprise architecture tools
Design documentation

Git Integration

Commit Messages

Reference ADRs in commits:

feat: implement event-driven order processing

Implements ADR-0012 (Event-Driven Architecture)

- Add order event publisher
- Create payment event handler
- Remove synchronous calls

Branch Naming

Include ADR reference:

feature/adr-0012-event-driven-orders
fix/adr-0015-auth-compliance

Pull Request Templates

## Related ADRs

- [ ] This PR implements ADR-XXXX
- [ ] This PR complies with accepted ADRs
- [ ] This PR proposes new ADR (link below)

### ADR Compliance Check

- [ ] Architecture patterns followed
- [ ] Technology choices match ADRs
- [ ] No ADR violations introduced

Automation Scripts

Index Generation

Auto-generate README.md index:

#!/bin/bash
# Generate ADR index from files

echo "# Architecture Decision Records"
echo ""
echo "| ID | Title | Status | Date |"
echo "|----|-------|--------|------|"

for file in docs/adr/[0-9]*.md; do
  # Extract metadata
  # Format table row
  echo "| $id | [$title]($file) | $status | $date |"
done

Link Validation

Check ADR cross-references:

#!/bin/bash
# Validate ADR links

for file in docs/adr/*.md; do
  # Find ADR references (ADR-XXXX)
  # Verify linked ADRs exist
  # Report broken links
done

Status Sync

Ensure bidirectional links:

#!/bin/bash
# Sync supersedes/superseded-by

for file in docs/adr/*.md; do
  # If A supersedes B
  # Verify B has superseded-by: A
done

Monitoring and Metrics

ADR Health Dashboard

Track metrics:

Total ADRs by status
ADRs created per month
Average time to accept
Supersession rate
Compliance violations

Alerts

Set up notifications for:

ADRs proposed > 30 days
Deprecated ADRs without successors
Compliance violations
Missing links/metadata

Configuration

Configure integrations in .claude/adr.local.md:

git:
  enabled: true
  auto_commit: false
  commit_template: "docs(adr): {action} ADR-{id} {title}"

export:
  default_format: html
  html_template: default
  include_toc: true
  output_dir: null

integration:
  docs_site: mkdocs
  issue_tracker: jira
  notifications: slack

Additional Resources

Reference Files

references/ci-templates.md - CI/CD pipeline templates
references/export-templates.md - Export format templates

adr-compliance - Compliance checking integration
adr-fundamentals - Basic ADR workflow