{"id":48582437,"url":"https://github.com/zircote/adr","last_synced_at":"2026-04-08T17:33:52.041Z","repository":{"id":333057999,"uuid":"1136076789","full_name":"zircote/adr","owner":"zircote","description":"Claude Code plugin for complete ADR lifecycle management with multi-format support (MADR, Nygard, Y-Statement), compliance auditing, and configurable workflows","archived":false,"fork":false,"pushed_at":"2026-03-30T20:32:17.000Z","size":368,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T22:20:34.919Z","etag":null,"topics":["adr","architecture-decision-records","claude-code","claude-code-plugin","documentation","madr"],"latest_commit_sha":null,"homepage":"https://zircote.com/adr/","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zircote.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"zircote"}},"created_at":"2026-01-17T02:54:55.000Z","updated_at":"2026-03-30T20:32:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zircote/adr","commit_stats":null,"previous_names":["zircote/adr"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zircote/adr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fadr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fadr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fadr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fadr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zircote","download_url":"https://codeload.github.com/zircote/adr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fadr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architecture-decision-records","claude-code","claude-code-plugin","documentation","madr"],"created_at":"2026-04-08T17:33:51.379Z","updated_at":"2026-04-08T17:33:52.033Z","avatar_url":"https://github.com/zircote.png","language":"MDX","readme":"# ADR Plugin\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://github.com/anthropics/claude-code)\n[![CI](https://github.com/zircote/adr/actions/workflows/ci.yml/badge.svg)](https://github.com/zircote/adr/actions/workflows/ci.yml)\n[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](https://github.com/zircote/adr/releases)\n\nComplete lifecycle management for Architectural Decision Records (ADRs): create, update, supersede, search, audit compliance, and export.\n\n## Features\n\n- **Multi-Format Support** - MADR, Structured MADR, Nygard, Y-Statement, Alexandrian, Business Case, Tyree-Akerman\n- **Full Lifecycle Management** - Create, update, supersede, deprecate, archive\n- **Compliance Auditing** - Proactive checks of code against accepted ADRs\n- **Research Assistant** - Codebase analysis and web research for decision context\n- **Proactive ADR Detection** - Agent suggests capturing architectural discussions\n- **Git Integration** - Track changes, auto-commit, blame history\n- **Export Options** - HTML, JSON, PDF for documentation and sharing\n- **Configurable Workflow** - Custom statuses, numbering, templates\n- **Multi-Directory Support** - Project-level and module-level ADRs\n- **ADR Linking** - Supersedes, relates-to, amends relationships\n\n## Installation\n\n### From GitHub\n\n```bash\nclaude plugin install zircote/adr\n```\n\n### Manual Installation\n\nClone and add to Claude Code:\n\n```bash\ngit clone https://github.com/zircote/adr.git\nclaude --plugin-dir /path/to/adr\n```\n\nOr copy to your project's `.claude-plugin/` directory.\n\n## Quick Start\n\n```bash\n# Initialize ADR configuration\n/adr:setup\n\n# Create your first ADR\n/adr:new \"Use PostgreSQL for Primary Storage\"\n\n# List all ADRs\n/adr:list\n\n# Search ADRs\n/adr:search \"database\"\n```\n\n## Components\n\n### Commands\n\n| Command | Arguments | Description |\n|---------|-----------|-------------|\n| `/adr:new` | `\u003ctitle\u003e` | Create a new ADR with specified title |\n| `/adr:list` | `[--status=\u003cstatus\u003e] [--format=table\\|json\\|brief]` | List all ADRs with optional filtering |\n| `/adr:update` | `\u003cid\u003e [--status=\u003cstatus\u003e]` | Update an existing ADR (status, content) |\n| `/adr:supersede` | `\u003cexisting-id\u003e \u003cnew-title\u003e` | Create ADR that supersedes an existing one |\n| `/adr:search` | `\u003cquery\u003e [--status=\u003cstatus\u003e] [--since=\u003cdate\u003e]` | Search ADRs by content, status, or date |\n| `/adr:setup` | (interactive) | Interactive configuration wizard |\n| `/adr:export` | `[--format=html\\|json\\|pdf] [--output=\u003cpath\u003e]` | Export ADRs to various formats |\n\n### Agents\n\n| Agent | Description |\n|-------|-------------|\n| `adr-author` | Proactively detects architectural discussions and suggests creating ADRs |\n| `adr-compliance` | Audits code changes against accepted ADRs for violations |\n| `adr-researcher` | Gathers context from codebase and web for decision documentation |\n\n### Skills\n\n#### Core Skills\n- **adr-fundamentals** - ADR basics, lifecycle management, best practices\n- **adr-decision-drivers** - Identifying and documenting decision drivers\n- **adr-quality** - Review criteria, completeness checks, writing quality\n\n#### Format Skills\n- **adr-format-madr** - MADR 4.0.0 format (default)\n- **adr-format-structured-madr** - MADR with frontmatter, comprehensive options, and audit sections\n- **adr-format-nygard** - Classic Nygard format\n- **adr-format-y-statement** - Concise Y-Statement format\n- **adr-format-alexandrian** - Pattern-based Alexandrian format\n- **adr-format-business-case** - MBA-style with SWOT and ROI\n- **adr-format-tyree-akerman** - Enterprise-grade comprehensive format\n\n#### Specialized Skills\n- **adr-compliance** - Compliance checking patterns and audit workflows\n- **adr-integration** - CI/CD integration, documentation sites, tooling\n\n## Configuration\n\nCreate `.claude/adr.local.md` in your project root (use `/adr:setup` for guided setup).\n\nSee `templates/adr.local.md.example` for a complete configuration template.\n\n```yaml\n---\n# ADR directories\nadr_paths:\n  - docs/adr/\n\n# Default template format\ndefault_format: madr\nmadr_variant: full\n\n# Numbering pattern\nnumbering:\n  pattern: \"4digit\"\n  start_from: 1\n\n# Status workflow\nstatuses:\n  workflow:\n    - proposed\n    - accepted\n    - deprecated\n    - superseded\n  allow_rejected: true\n\n# Git integration\ngit:\n  enabled: true\n  auto_commit: false\n\n# Compliance checking\ncompliance:\n  enabled: true\n  check_all_accepted: true\n  file_patterns:\n    - \"**/*.ts\"\n    - \"**/*.py\"\n---\n\n# Project ADR Context\n\nAdd project-specific notes here...\n```\n\n## ADR Status Workflow\n\n```\nproposed → accepted → [deprecated] → superseded\n              ↓\n          rejected\n```\n\n| Status | Description |\n|--------|-------------|\n| **proposed** | Decision under consideration |\n| **accepted** | Approved and active |\n| **rejected** | Considered but not adopted |\n| **deprecated** | No longer recommended |\n| **superseded** | Replaced by another ADR |\n\n## Template Formats\n\n### MADR (Default)\nMarkdown Architectural Decision Records - lean, option-focused format with pros/cons analysis.\n\n### Structured MADR\nExtended MADR with YAML frontmatter, comprehensive option analysis with risk assessments, and required audit sections. Best for regulated environments.\n\n### Nygard\nClassic 5-section format: Title, Status, Context, Decision, Consequences.\n\n### Y-Statement\nSingle-sentence format capturing context, concern, option, quality, and trade-off.\n\n### Alexandrian\nPattern-oriented format emphasizing forces and resulting context.\n\n### Business Case\nExecutive-focused with SWOT analysis, cost-benefit, and ROI assessment.\n\n### Tyree-Akerman\nComprehensive enterprise format with full traceability to requirements and principles.\n\n## File Structure\n\n```\nadr/\n├── .claude-plugin/\n│   └── plugin.json\n├── agents/\n│   ├── adr-author.md\n│   ├── adr-compliance.md\n│   └── adr-researcher.md\n├── commands/\n│   ├── adr-export.md\n│   ├── adr-list.md\n│   ├── adr-new.md\n│   ├── adr-search.md\n│   ├── adr-setup.md\n│   ├── adr-supersede.md\n│   └── adr-update.md\n├── schemas/\n│   └── adr-export.schema.json\n├── skills/\n│   ├── adr-compliance/\n│   ├── adr-decision-drivers/\n│   ├── adr-format-alexandrian/\n│   ├── adr-format-business-case/\n│   ├── adr-format-madr/\n│   ├── adr-format-nygard/\n│   ├── adr-format-structured-madr/\n│   ├── adr-format-tyree-akerman/\n│   ├── adr-format-y-statement/\n│   ├── adr-fundamentals/\n│   ├── adr-integration/\n│   └── adr-quality/\n├── templates/\n│   ├── alexandrian/\n│   ├── business-case/\n│   ├── madr/\n│   ├── nygard/\n│   ├── structured-madr/\n│   ├── tyree-akerman/\n│   ├── y-statement/\n│   ├── adr.local.md.example\n│   └── README-index.md\n├── CHANGELOG.md\n├── LICENSE\n└── README.md\n```\n\n## References\n\n- [MADR](https://adr.github.io/madr/) - Markdown Architectural Decision Records\n- [ADR Templates](https://adr.github.io/adr-templates/) - Various ADR formats\n- [Michael Nygard's ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - Original ADR concept\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/zircote"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fadr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzircote%2Fadr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fadr/lists"}