adr-generator

name: adr-generator version: 1.1.0 model: claude-opus-4-6 description: Create comprehensive Architectural Decision Records (ADRs). Researches the destination directory to detect existing template conventions, gathers context, determines next ADR number, generates the ADR, validates completeness, and saves. Supports multiple ADR formats (MADR, Nygard, Alexandrian, project canonical). Use when documenting technical decisions or creating new ADR files. Use when you say "write an ADR", "document this decision". Do NOT use to debate or review an existing ADR (use adr-review). license: MIT user-invocable: true metadata: domains: [architecture, documentation, governance, decision-records] type: generator inputs: [decision-description, context, alternatives] outputs: [adr-markdown-file]

ADR Generator

Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.

Triggers

Quick Start

# These all work:
create an ADR for database selection
new ADR for authentication strategy
document this architecture decision about event sourcing
generate ADR for switching from REST to gRPC

When to Use

Process

Phase G1: Gather

Collect required information from the user:

• Decision Title: Clear, concise name
• Context: Problem statement, technical constraints, business requirements
• Decision: Chosen solution with rationale
• Alternatives: Options considered (at least 2) and rejection reasons
• Stakeholders: People or teams involved

If any required information is missing, ask the user before proceeding.

Significance check: Before proceeding, quickly assess whether the decision warrants an ADR using the ASR Test. If the decision is trivially reversible, purely local, and has no stakeholder concern, suggest skipping the ADR.

Readiness check: Verify the decision passes the START Definition of Ready: Stakeholders known, Time (Most Responsible Moment) has come, Alternatives exist, Requirements understood, Template will be determined in G2.

If the decision changes an existing system, trigger Prior Art Investigation using the chestertons-fence skill or manually gather: what exists, why it was built that way, and why change now.

Phase G2: Research

Discover the ADR destination, naming convention, numbering, and template by exploring the codebase.

Step 1: Locate ADR directory

Explore the codebase to find where ADRs live. Do not assume a fixed location.

1. Search broadly: Use glob/grep to find files matching ADR patterns (ADR-*.md, adr-*.md, 0*-*.md in directories named decisions, adr, architecture)
2. Check common locations: .agents/architecture/, docs/adr/, docs/architecture/, docs/decisions/, architecture/decisions/
3. Check for ADR tooling config: Look for .adr-dir files (used by adr-tools) or ADR references in README, CONTRIBUTING, or project documentation
4. If user specifies a location: Use that, regardless of what exists elsewhere

Note: .agents/architecture/ and docs/architecture/ are monitored by adr-review for auto-triggered review. ADRs in other directories require manual adr-review invocation.

Step 2: Detect template from existing ADRs

If the directory contains existing ADRs:

• Read 2-3 existing ADRs to infer the template in use (section headings, frontmatter style, naming convention, case convention)
• Match against known templates in the ADR templates catalog
• Adopt the detected template, naming convention (e.g., ADR-NNN-slug.md vs 0NNN-slug.md), and section structure
• Note: adr-review auto-triggers only match uppercase ADR-*.md patterns. If existing ADRs use lowercase, warn the user that auto-review will not trigger
• Check for a template file (e.g., ADR-TEMPLATE.md, template.md) in the same directory or a parent

Step 3: Handle no existing ADRs

If no ADRs or template files exist anywhere in the codebase:

• Prompt the user to choose a template from the catalog
• Suggest the Project Canonical template as the default (if .agents/architecture/ADR-TEMPLATE.md exists) or MADR as a widely-adopted alternative
• Ask the user to confirm or specify the target directory

Step 4: Determine next number

• Scan files matching the detected naming pattern in the destination directory
• Determine the next sequential number (zero-padded to match existing convention)
• Verify no collision with existing files in that directory

For this repo's canonical .agents/architecture/ location, use the deterministic helper instead of eyeballing the directory (it also accounts for the #2228 allowlist of pre-existing duplicates):

python3 scripts/validation/check_adr_uniqueness.py --print-next

The same script is enforced as a merge-time CI gate (.github/workflows/validate-adr-number-uniqueness.yml, issue #2253), so a PR that picked a number which has since been merged by another branch will fail with a remediation message naming the next free value. Re-run --print-next and rename the file, the # ADR-NNN: heading, and any references before pushing.

Phase G3: Generate

Populate the detected template with gathered content:

• Use precise, unambiguous language
• Include both positive and negative consequences
• Document all alternatives with pros/cons table and clear rejection rationale
• Include Prior Art Investigation section when changing existing systems
• Structure for both machine parsing and human reference
• Match the style and conventions of existing ADRs at the destination

Lifecycle frontmatter (ADR-073, Phase 1): when the destination uses this repo's canonical template (.agents/architecture/ADR-TEMPLATE.md), emit the

machine-readable YAML frontmatter block above the # ADR-NNN: heading with these safe defaults:

---
id: ADR-NNN              # match the number chosen in Step 4
status: proposed         # always proposed on a new ADR (never accepted)
date: YYYY-MM-DD         # today, last-updated
decision-makers: []
supersedes: []           # ADR ids this record supersedes, if any
superseded-by: null
explainer: null          # display-only link; NEVER auto-fetch (CWE-918 SSRF)
implemented: false       # flips true at the first merged change
---

Rules the generator MUST honor:

• status is always proposed on a new ADR. Only adr-review consensus changes it (see Phase G5 and the Anti-Patterns table).
• implemented is always false on a new ADR; it flips at first merged change.
• superseded-by defaults to null; supersedes defaults to [].
• explainer defaults to null. If the author supplies one, record the literal string only. MUST NOT fetch, resolve, or follow the URL (it is a poisoning and SSRF surface, CWE-918). It is display-only metadata for human click-through.
• The frontmatter status enum is authoritative for tooling; the prose ## Status section carries the human-readable nuance.

Phase G4: Validate

Self-check against the quality checklist before saving. All structural and content checks must pass.

Phase G5: Save

Write the file to the destination directory determined in Phase G2:

After saving, recommend the user invoke the adr-review skill for multi-agent validation.

Anti-Patterns

Avoid these when creating ADRs. Full catalog with 11+ creation and 7 review anti-patterns in AD Quality Frameworks.

Style

• No sycophancy, AI filler phrases, or hedging language
• Active voice, direct address
• Replace adjectives with data (quantify impact)
• Short sentences (15-20 words), Grade 9 reading level

Verification

Before delivering, confirm all items in the quality checklist pass:

• All required sections present
• ADR number is unique
• Status is Proposed
• Context explains the problem, not the solution
• At least 2 alternatives with pros/cons
• At least 1 negative consequence documented
• File saved to destination directory determined in Phase G2

Related Skills

References

• ADR Template: This project's canonical ADR document structure
• ADR Templates Catalog: Comparison of Nygard, MADR, Alexandrian, Tyree & Akerman, and other formats
• AD Quality Frameworks: ASR Test, START (DoR), ecADR (DoD), anti-patterns, review checklist (Zimmermann)
• ADR Best Practices: Writing guidance, lifecycle, naming conventions, teamwork advice
• Quality Checklist: Validation checklist for Phase G4