Architecture Decision Record (ADR) Command

Document architecture decisions following the ADR pattern. Auto-generates next ADR number and updates index.

Arguments

• Optional: <decision_context> - If provided, document that specific decision
• No argument: Infer decision from recent conversation context

Pre-Flight Checks

1. Ensure ADR directory exists:

   • Check for adrs/ directory in current working directory
   • If missing: Create adrs/ directory

2. Ensure index exists:

   • Check for adrs/000-index.md
   • If missing: Create default index template:

     # Architecture Decision Records (ADR) Index
     
     > Critical decisions that govern development. **Read before implementing.**
     
     ## Index
     
     | # | Decision | Status | Date |
     |---|----------|--------|------|
     
     ## Usage
     
     ADRs document significant architectural and policy decisions. Each entry follows format:
     `NNN-<title>.md` where NNN is zero-padded sequence number.
     
     ### Creating New ADR
     Use `/adr` command or manually:
     1. Create file `adrs/NNN-title.md`
     2. Add entry to this index
     3. Commit: `adr(NNN): <title>`
     

3. Read ADR index: adrs/000-index.md

   • Extract highest existing ADR number
   • Generate next number (NNN format: zero-padded 3 digits)

4. Validate decision context:

   • If argument provided: Use that as decision context
   • If no argument: Infer from recent conversation (last 2-3 messages)
   • If unclear: STOP and ask user to clarify decision to document

Execution

1. Generate ADR metadata:

   • Number: Next sequential (e.g., 001, 002, 003)
   • Title: Extract from decision context (kebab-case slug)
   • Date: Current date (YYYY-MM-DD format)
   • Status: "Accepted" (default)

2. Create ADR file: adrs/NNN-<slug>.md

   # NNN - <Title>
   
   **Status**: Accepted
   **Date**: <YYYY-MM-DD>
   
   ## Context
   <Why this decision was needed - problem statement, constraints, requirements>
   
   ## Decision
   <What was decided - clear statement of the chosen approach>
   
   ## Consequences
   <Implications and trade-offs:>
   - **Positive**: <benefits>
   - **Negative**: <costs, limitations>
   - **Neutral**: <other impacts>
   
   ## References
   <Related docs, specs, links if any>
   

3. Update index: adrs/000-index.md

   • Add new row to table:

     | NNN | [<Title>](./NNN-<slug>.md) | Accepted | YYYY-MM-DD |
     

4. Commit changes:

   git add adrs/NNN-<slug>.md adrs/000-index.md && git commit -m "adr(NNN): <title>"
   

Output

Report in markdown format:

• ADR number created
• File path (absolute)
• Title
• Commit status

Example Usage

/adr Use pnpm for package management

Creates:

• File: adrs/001-use-pnpm-for-package-management.md
• Updates: adrs/000-index.md
• Commit: adr(001): use pnpm for package management