adr

Files (4)

• plugin.json · .claude-plugin/
• README.md
• SKILL.md
• metadata.json

SKILL.md (first lines)

# adr

## Purpose

Create, list, update, and supersede Architecture Decision Records (ADRs) following the Markdown Architectural Decision Records (MADR) 4.0 format. Maintains an ADR directory (see Directory Convention below). Works standalone or as a companion to `/architecture-design`.

---

## Directory Convention

Before creating anything, detect where this project keeps ADRs. Use Glob to check, in order: `docs/decisions/ADR-*.md`, `docs/decisions/[0-9][0-9][0-9][0-9]-*.md`, `docs/adr/*.md`, `adr/*.md`, `docs/architecture/decisions/*.md`. Use the first directory that already contains ADRs. Only if none exists, default to `docs/decisions/`. All paths below refer to this detected directory. If existing ADRs use a different file-name pattern (e.g. MADR's `NNNN-title.md`), follow that pattern instead of `ADR-NNN-title.md`.

---

## ADR Format (MADR 4.0)

Every ADR follows the MADR 4.0.0 template (<https://adr.github.io/madr/>). Metadata lives in YAML front matter. `tags` is not part of MADR; this skill adds it as an optional key so `list` and `search` can filter by area. Sections marked `<!-- optional -->` may be dropped when they add nothing; remove the marker comments from the saved file.

```markdown
---
status: proposed | accepted | rejected | deprecated | superseded by ADR-NNN
date: YYYY-MM-DD
decision-makers: <names or roles>
consulted: <people whose opinions were sought; two-way communication>
informed: <people kept up to date; one-way communication>
tags: <architecture | security | database | api | infrastructure | ...>
---

# ADR-NNN: <Title>

## Context and Problem Statement

[2-3 sentences: what situation led to this decision? What problem is being solved? Phrase it as a question if that helps.]

<!-- optional -->
## Decision Drivers

* [driver 1: most important constraint or goal]
* [driver 2]

## Considered Options

* [Option A]
* [Option B]
* [Option C]

## Decision Outcome

Chosen option: "[Option A]", because [justification tied to the decision drivers].

<!-- optional -->
### Consequences

* Good, because [what becomes easier, better, or possible]
* Bad, because [what becomes harder, more expensive, or is given up]
* Neutral, because [effect that is neither a gain nor a loss]

<!-- optional, but include it whenever possible -->
### Confirmation

[How compliance with this decision will be checked: design or code review, an architecture test (e.g. ArchUnit), a lint rule, a CI check.]

<!-- optional -->
## Pros and Cons of the Options

### [Option A]

* Good, because [argument]
* Neutral, because [argument]
* Bad, because [argument]

### [Option B]

* Good, because [argument]
* Bad, because [argument]

<!-- optional -->
## More Information

[Supporting evidence, team agreement, when to revisit the decision, links to related ADRs, design docs, RFCs, or tickets.]
```

---

## Instructions

### Step 1 — Determine the action

Parse `$ARGUMENTS` first and dispatch directly — do not ask if the action is given:

| Invocation | Action |
|------------|--------|
| `/adr create <title>` | Step 2a, using `<title>` as the decision title |
| `/adr list` | Step 2b |
| `/adr update <n> <status>` | Step 2c on ADR-`<n>`, setting `<status>` |
| `/adr supersede <n>` | Step 2d replacing ADR-`<n>` |
| `/adr search <keyword>` | Step 2e with `<keyword>` |

If no arguments were given, ask the user what they want to do:
- **(a) Create a new ADR** — document a new architectural decision
- **(b) List existing ADRs** — show all ADRs with status and one-line summary
- **(c) Update an ADR's status** — mark as Accepted, Rejected, Deprecated, or Superseded
- **(d) Supersede an ADR** — create a new ADR that replaces an existing one
- **(e) Search ADRs** — find ADRs by tag, status, or keyword

---

### Step 2a — Create a new ADR

1. Use Glob to find all existing ADRs in the detected ADR directory. Determine the next number.
2. Use Read on any related existing ADRs mentioned.
3. Ask the user (skip the title question if it was passed as an argument):
   - What is the decision being made? (one sentence title)
   - What is the context / problem? (what forced this decision)
   - Who made the decision? Who was consulted, and who needs to be informed?
   - What options were considered?
   - What was chosen and why?
   - How will compliance be confirmed (review, test, CI check)?
4. Generate the full ADR using the MADR format above.

From RealDougEubanks/ClaudeMarketplace, MIT.

More from RealDougEubanks/ClaudeMarketplace