x-adr

Draft architectural decision records using adr-template.md and update the ADR index.

1|Updated May 28, 2026
One-click install
npx skills add https://github.com/amoutiers/maxi-superpowers --skill x-adr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: x-adr
Source: https://github.com/amoutiers/maxi-superpowers/tree/main/skills/x-adr
Command: npx skills add https://github.com/amoutiers/maxi-superpowers --skill x-adr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Architectural decisions are often scattered and hard to audit. This skill ensures ADRs are drafted, reviewed, and stored with explicit consent, preserving rationale and traceability.

Core Features & Use Cases

  • Draft ADRs using adr-template.md and auto-assign a sequential number.
  • Check for contradictions with existing ADRs and surface potential supersede candidates.
  • Link ADRs to active specs by updating related_adrs and the spec's updated date.
  • Require explicit user approval before writing any ADR file.
  • Maintain ADR index and reflect status changes (accepted, superseded).

Quick Start

Draft a new ADR with the template, present it for approval, and commit docs/maxi/adr/NNNN-slug.md once approved.

Frequently Asked Questions about x-adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document architectural decisions and track their rationale?

Architectural decisions are documented using an ADR template that captures the rationale behind design choices. This skill drafts ADRs, assigns sequential numbers, and stores them in a structured directory to preserve traceability and governance.

How do I check a new architecture decision for contradictions with existing records?

Checking a new architecture decision for contradictions involves comparing the drafted ADR against existing records to surface potential conflicts. The skill identifies supersede candidates and updates the ADR index to reflect status changes.

Can I link architectural decision records to active project specifications?

Yes, architectural decision records can be linked to active project specifications. The skill updates the related_adrs field in the spec and adjusts the spec's updated date to maintain accurate traceability between governance and implementation.

What is the best way to enforce a standard ADR template structure across a project?

The best way to enforce a standard ADR template structure is to use a skill that mandates the adr-template.md format. It requires explicit user approval before writing any file, ensuring all records conform to the project's governance standards.

How do I manage ADR supersession and status updates in the index?

Managing ADR supersession and status updates is handled automatically when a new decision replaces an old one. The skill updates the ADR index with accepted or superseded statuses, created and updated dates, and supersession information.