Note: This is the canonical ADR skill for the plugin ecosystem. For detailed ADR templates (Nygard, MADR, Enterprise), use MCP tools (

perplexity

,

context7

) to research current best practices.

• Document a technology choice or design decision
• Record why a particular approach was selected over alternatives
• Track the history of architectural decisions
• Create a searchable record of decisions for team onboarding

1. Determine the next ADR number
   • Check existing ADRs in

     /architecture/adr/

   • Use sequential numbering: 0001, 0002, 0003, etc.
2. Create the ADR file
   • Location:

     /architecture/adr/NNNN-title-in-kebab-case.md

   • Use the template from

     references/adr-template.md

3. Fill in required sections
   • Status: Start with "Proposed"
   • Date: Current date in YYYY-MM-DD format
   • Context: Describe the problem and constraints
   • Decision: State the decision clearly
   • Consequences: List positive, negative, and neutral outcomes
4. Document alternatives
   • List each alternative considered
   • Include pros, cons, and why it was rejected
5. Optional: Generate context diagram
   • If visualization plugin is available, generate a diagram showing the decision's context
   • Spawn the

     visualization:diagram-generator

     agent for C4 or component diagrams
   • Or use the

     visualization:diagram-patterns

     skill for diagram type guidance

1. Update the old ADR's status to "Superseded by ADR-XXXX"
2. Reference the old ADR in the new ADR's "Related Decisions" section

• Implements a principle
• Makes a trade-off against a principle
• Establishes a new principle

references/adr-template.md

• Status: Current state of the decision
• Date: When the decision was made
• Deciders: Who was involved
• Context: Problem and constraints
• Decision: What was decided
• Consequences: Outcomes (positive, negative, neutral)
• Alternatives Considered: What else was evaluated
• Related Decisions: Links to related ADRs
• References: Supporting documentation

1. One decision per ADR - Keep ADRs focused
2. Immutable history - Never delete ADRs, only supersede
3. Link decisions - Reference related ADRs
4. Include context - Future readers need to understand the constraints
5. Be honest about trade-offs - Document negative consequences too

1. Determine next ADR number by scanning existing ADRs in

   /architecture/adr/

   (sequential: 0001, 0002, etc.)
2. Create the ADR file using the standard template with sequential numbering, initial status "Proposed", current date (UTC), and title from arguments
3. Report the created file path so the user can complete the Context, Decision, and Consequences sections

• v1.0.0 (2025-12-05): Initial release
  • ADR creation and management workflow
  • Status lifecycle documentation
  • Integration with architecture principles
  • Template reference and best practices