FoundryVTT/.claude/commands/adr.md

description: Manage Architectural Decision Records (ADRs) - list, view, create, or update architectural decisions allowed-tools: Read(), mcp__serena__list_memories(), mcp__serena__read_memory(), mcp__serena__write_memory(), Task(*) argument-hint: [list|view|create|update] [adr-number-or-name]

ADR Command

Manage Architectural Decision Records (ADRs) to document important architectural and technical decisions.

What are ADRs?

Architectural Decision Records (ADRs) are documents that capture important architectural decisions along with their context and consequences. They help teams:

• Understand why decisions were made
• Maintain consistency across the codebase
• Onboard new team members faster
• Avoid repeating past mistakes
• Track the evolution of system architecture

Usage

# List all ADRs
/adr list

# View a specific ADR
/adr view adr-001
/adr view adr-003-authentication-strategy

# Create a new ADR
/adr create

# Update/supersede an existing ADR
/adr update adr-002

Instructions

When user runs: /adr list

1. Use Serena MCP list_memories to find all memories starting with "adr-"
2. Parse and display them in a formatted table:

## Architectural Decision Records

| ADR # | Status | Title | Date |
|-------|--------|-------|------|
| 001   | Accepted | Microservices Architecture | 2024-10-15 |
| 002   | Accepted | PostgreSQL Database Choice | 2024-10-18 |
| 003   | Proposed | Event-Driven Communication | 2025-10-20 |
| 004   | Deprecated | MongoDB (superseded by ADR-002) | 2024-10-10 |

**Total ADRs**: 4
**Active**: 2 | **Proposed**: 1 | **Deprecated/Superseded**: 1

3. Provide summary statistics
4. Offer to view specific ADRs or create new ones

When user runs: /adr view [number-or-name]

1. Use Serena MCP read_memory with the specified ADR name
2. Display the full ADR content
3. Highlight key sections:
   • Decision outcome
   • Related ADRs
   • Status
4. Check for related ADRs and offer to view them
5. If ADR is deprecated/superseded, show which ADR replaced it

When user runs: /adr create

1. Check existing ADRs to determine next number:

   • Use list_memories to find all "adr-*"
   • Find highest number and increment
   • If no ADRs exist, start with 001

2. Ask clarifying questions:

   • What architectural decision needs to be made?
   • What problem does this solve?
   • What are the constraints?
   • What options have you considered?

3. Invoke architect agent with Task tool:

   • Pass the user's requirements
   • Agent will create structured ADR
   • Agent will ask to save to Serena memory

4. Confirm ADR creation:

   • Show ADR number assigned
   • Confirm it's saved to Serena memory
   • Suggest reviewing related ADRs

When user runs: /adr update [number]

1. Load existing ADR:

   • Use read_memory to load the specified ADR
   • Display current content

2. Determine update type:

   • Ask: "What type of update?"
     • Supersede (replace with new decision)
     • Deprecate (mark as no longer valid)
     • Amend (update details without changing decision)

3. For Supersede:

   • Create new ADR using /adr create process
   • Mark old ADR as "Superseded by ADR-XXX"
   • Update old ADR in memory
   • Link new ADR to old one

4. For Deprecate:

   • Update status to "Deprecated"
   • Add deprecation reason and date
   • Save updated ADR

5. For Amend:

   • Invoke architect agent to help with amendments
   • Maintain version history
   • Save updated ADR

ADR Format

All ADRs should follow this standard format (see architect agent for full template):

# ADR-XXX: [Decision Title]

**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date**: [YYYY-MM-DD]

## Context and Problem Statement
[What problem requires a decision?]

## Decision Drivers
- [Key factors influencing the decision]

## Considered Options
### Option 1: [Name]
- Pros: [...]
- Cons: [...]

## Decision Outcome
**Chosen option**: [Option X] because [justification]

## Consequences
- Positive: [...]
- Negative: [...]

[Additional sections as needed]

Best Practices

When to Create an ADR

Create an ADR when making decisions about:

• Architecture: System structure, component boundaries, communication patterns
• Technology: Language, framework, database, or major library choices
• Security: Authentication, authorization, encryption approaches
• Infrastructure: Deployment, hosting, scaling strategies
• Standards: Coding standards, testing approaches, monitoring strategies

When NOT to Create an ADR

Don't create ADRs for:

• Trivial decisions that don't impact architecture
• Decisions easily reversible without significant cost
• Implementation details within a single component
• Personal preferences without architectural impact

ADR Lifecycle

1. Proposed: Decision is being considered
2. Accepted: Decision is approved and should be followed
3. Deprecated: No longer recommended but may still exist in code
4. Superseded: Replaced by a newer ADR

Integration with Other Agents

• architect: Creates and updates ADRs
• code-reviewer: Validates code aligns with ADRs
• security-analyst: Ensures security ADRs are followed
• project-manager: Loads ADRs to inform workflow planning

Examples

Example 1: Team wants to understand past decisions

User: /adr list

Agent lists all ADRs with status, allowing team to understand architectural history.

Example 2: Reviewing specific decision

User: /adr view adr-003-authentication-strategy

Agent shows full ADR with rationale, alternatives, and consequences.

Example 3: Making new architectural decision

User: /adr create
Agent: What architectural decision needs to be made?
User: We need to choose between REST and GraphQL for our API
Agent: [Asks clarifying questions, invokes architect agent]
Agent: Created ADR-005-api-architecture-graphql. Saved to Serena memory.

Example 4: Superseding old decision

User: /adr update adr-002
Agent: [Shows current ADR-002: MongoDB choice]
Agent: What type of update? (supersede/deprecate/amend)
User: supersede - we're moving to PostgreSQL
Agent: [Creates ADR-006, marks ADR-002 as superseded]

Notes

• ADRs are stored in Serena memory (.serena/memories/)
• ADRs persist across sessions
• All agents can read ADRs to inform their work
• Architect agent is responsible for creating properly formatted ADRs
• Use sequential numbering (001, 002, 003, etc.)
• Keep ADRs concise but comprehensive
• Update ADRs rather than deleting them (maintain history)