Implement docs-ddr: Architecture Decision Records

[vredchenko]

Summary

The docs-ddr plugin manages Architecture Decision Records (ADRs) — lightweight documents that capture the "why" behind significant technical choices. This is valuable because ADRs are easy to forget in the flow of development, and a PostToolUse hook can prompt their creation when Claude makes structural changes.

Original Intent

Architecture Decision Records — maintain a record of project decisions explaining significant choices made as markdown documents tracked under version control. Configure Claude Code to identify when a decision is made that needs documenting, as well as reference existing ADRs to be aware of established choices for the project.

Commands

/adr:new

Purpose: Create a new ADR with the next sequential number.

Behavior:

1. Determine ADR directory:
   • Check for existing: docs/adr/, docs/decisions/, adr/, decisions/
   • If none exists → create docs/adr/ (default)
2. Find next number:
   • Scan existing ADR files matching NNNN-*.md pattern
   • Next = max(existing) + 1, zero-padded to 4 digits
3. Ask user for:
   • Title (required): short descriptive phrase
   • Context (required): what is the issue being decided?
   • Decision drivers (optional): key factors influencing the choice
4. Generate ADR file using Michael Nygard template:

   # ADR-NNNN: <Title>
   
   ## Status
   
   Proposed
   
   ## Context
   
   <User-provided context>
   
   ## Decision Drivers
   
   - <driver 1>
   - <driver 2>
   
   ## Considered Options
   
   1. **<Option A>** — <brief description>
   2. **<Option B>** — <brief description>
   
   ## Decision
   
   We will use **<chosen option>** because <reasoning>.
   
   ## Consequences
   
   ### Positive
   - <positive consequence>
   
   ### Negative
   - <negative consequence>
   
   ### Neutral
   - <neutral consequence>
   
   ## References
   
   - <links to relevant docs, issues, PRs>

5. Guide user through filling in each section interactively
6. If this is the first ADR, also create:
   • docs/adr/0000-record-architecture-decisions.md (meta-ADR)
   • docs/adr/README.md (index/explanation of what ADRs are)
7. Output: ✓ Created docs/adr/NNNN-<slug>.md

Edge cases:

• ADR supersedes an existing one → update old ADR's status to "Superseded by ADR-NNNN"
• Non-sequential numbering (gaps) → use max+1, don't fill gaps
• Existing ADR with same title slug → append suffix or ask user to rename

/adr:list

Purpose: Display all ADRs with their status.

Behavior:

1. Find ADR directory (same detection as new)
2. Parse each ADR file:
   • Extract number from filename
   • Extract title from # heading
   • Extract status from ## Status section
3. Display formatted table:

   Architecture Decision Records (docs/adr/)
   
   | #    | Title                                  | Status      |
   |------|----------------------------------------|-------------|
   | 0000 | Record Architecture Decisions           | Accepted    |
   | 0001 | Use PostgreSQL for primary database     | Accepted    |
   | 0002 | Adopt React for frontend               | Accepted    |
   | 0003 | Switch from REST to GraphQL            | Superseded  |
   | 0004 | Use tRPC instead of GraphQL            | Proposed    |
   

4. Show summary: "4 accepted, 1 superseded, 1 proposed"
5. If user asks about a specific ADR → read and summarize it

Edge cases:

• No ADR directory exists → suggest running /adr:new first
• Non-standard ADR format → best-effort parsing, warn about unparseable files

/adr:update (new)

Purpose: Update the status or content of an existing ADR.

Behavior:

1. Ask user which ADR to update (by number or fuzzy title match)
2. Read the ADR file
3. Common updates:
   • Change status: Proposed → Accepted, Accepted → Deprecated, Accepted → Superseded
   • Add consequences: After living with the decision, add observed consequences
   • Add references: Link to implementation PRs, follow-up ADRs
4. If changing to "Superseded":
   • Ask which ADR supersedes it
   • Add "Superseded by ADR-NNNN" to the status section
   • Add "Supersedes ADR-MMMM" to the new ADR
5. Update the file
6. Output: ✓ Updated ADR-NNNN status: Proposed → Accepted

Hooks

PostToolUse: adr_suggestion

Trigger: Bash tool, when the command involves:

• Adding a new major dependency (bun add, uv add, cargo add, go get)
• Creating infrastructure files (docker-compose.yml, Dockerfile, terraform/, .github/workflows/)
• Significant config changes (new tsconfig.json, database migration files, API schema changes)

Detection patterns:

bun add (?!-d)            # non-dev dependency
uv add (?!--dev)          # non-dev dependency
cargo add                 # any cargo dependency
go get                    # any go dependency

File creation patterns:

docker-compose, Dockerfile, .github/workflows/, terraform/, migrations/

Behavior:

• Output: 💡 Structural change detected. Consider documenting this decision with /adr:new
• Do NOT block — this is informational only
• Rate-limit: only suggest once per session per trigger type

File Manifest

File	Est. Lines	Purpose
commands/new.md	90-110	Create new ADR
commands/list.md	60-80	List all ADRs
commands/update.md	70-90	Update existing ADR
hooks/adr_suggestion.md	30-40	Suggest ADR on structural changes
README.md	140-170	Full plugin documentation
.claude-plugin/plugin.json	15-20	Plugin manifest

README Outline

1. Overview — What ADRs are and why they matter
2. Quick Start — Installation + creating your first ADR
3. Commands — Table with all 3 commands
4. Hooks — When and why the plugin suggests new ADRs
5. ADR Template — Full Michael Nygard template with explanations for each section
6. Status Lifecycle — Proposed → Accepted → (Deprecated | Superseded)
7. Best Practices — When to write an ADR, how detailed to be, what doesn't need one
8. References — Links to Michael Nygard's original article, adr-tools, etc.

Prerequisites

• No external tools required — ADRs are just markdown files

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• ADR template follows Michael Nygard format
• Plugin provides clear value beyond Claude's defaults (auto-suggestion hook is the key differentiator)
• Status lifecycle is documented