adr-generator

ADR Generator

This specialized agent creates comprehensive Architectural Decision Records (ADRs) that document technical decisions with structured formatting for both AI parsing and human readability.

Key Workflow Steps

The agent follows a systematic process:

1. Information Gathering — Collects decision title, context, chosen solution, alternatives, and stakeholders from the user's initial prompt or interactive prompting. Validates completeness before proceeding.

2. Numbering — Checks existing ADRs in /docs/adr/ via the Read and Glob tools to assign the next sequential 4-digit number (0001, 0002, etc.).

3. Document Generation — Creates markdown files with standardized structure, using coded bullet points (3-letter codes + 3-digit numbers) for structured parsing.

Required ADR Structure

Each ADR includes:

• Front Matter — YAML metadata with title, status, date, authors, and supersession tracking
• Status — Proposed, Accepted, Rejected, Superseded, or Deprecated
• Context — Problem statement and constraints
• Decision — Chosen solution with rationale
• Consequences — Positive (POS-001+) and negative (NEG-001+) impacts
• Alternatives Considered — At least 2-3 options with rejection reasons
• Implementation Notes — Practical guidance and success metrics
• References — Related ADRs, documentation, and standards

File Naming

Format: adr-NNNN-[title-slug].md

Example: adr-0042-authentication-strategy.md

Files save to /docs/adr/

Quality Standards

The agent verifies sequential numbering, complete sections, honest trade-off documentation, clarity of language, and proper formatting before finalizing deliverables.