# Adr

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-joaquimscosta-arkhe-claude-plugins-adr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [joaquimscosta](https://agentstack.voostack.com/s/joaquimscosta)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [joaquimscosta](https://github.com/joaquimscosta)
- **Source:** https://github.com/joaquimscosta/arkhe-claude-plugins/tree/main/plugins/doc/skills/adr

## Install

```sh
agentstack add skill-joaquimscosta-arkhe-claude-plugins-adr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ADR Manager

Create and manage Architecture Decision Records following project conventions with automatic numbering and index maintenance.

## Argument Parsing

When invoked explicitly with `/adr `, parse the first word:

| First word | Remaining args | Operation |
|------------|---------------|-----------|
| `create` | `` | Create a new ADR with the given title |
| `review` | `` | Lightweight quality review of an ADR |
| `status` | ` ` | Transition ADR status with validation and side effects |
| `list` | (none) | List all ADRs (same as running `adr_index.py --dry-run`) |
| `supersede` | ` ` | Supersede an old ADR with a new one |
| `index` | (none) | Regenerate the README.md index |
| (empty) | | Auto-detect from conversation context |

If the first word doesn't match an action, treat the entire `$ARGUMENTS` as a title and default to `create`.

When auto-invoked (no explicit `/adr` command), detect the operation from conversation context as before.

## Auto-Invoke Triggers

This skill automatically activates when:
1. **Keywords**: "ADR", "architecture decision", "document this decision", "record the decision"
2. **Editing ADR files**: Files in `docs/adr/`, `doc/adr/`, `architecture/decisions/`, `.adr/`
3. **Discussing architectural choices**: Framework selection, technology decisions, pattern choices

## What This Skill Delivers

### 1. ADR Creation (Enhanced)
- Gather context from conversation, codebase, and existing ADRs
- Confirm decision topic with user before drafting
- Auto-detect project's ADR directory and template style
- Auto-number ADRs (scan existing, increment)
- Draft populated ADR with real content (not blank template)
- Always append Author's Notes section (2-5 items)
- Offer MADR 4.0 enhancements as optional additions
- Suggest `/adr review ` after creation

### 2. Directory Discovery
Search order for ADR directories:
1. `docs/adr/`
2. `doc/adr/`
3. `architecture/decisions/`
4. `.adr/`
5. Create `docs/adr/` if none exists

### 3. Template Detection
Analyze existing ADRs to detect:
- Naming convention: `NNNN-kebab-case-title.md` or `NNN-title.md`
- Section structure: Status, Context, Decision, Consequences
- Optional sections: Decision Drivers, Pros/Cons, Confirmation

### 4. Index Maintenance
Automatically update README.md with ADR table:
| Number | Title | Status | Date |
|--------|-------|--------|------|

### 5. Supersession Workflow
When replacing an ADR:
- Mark old ADR status as "Superseded by [ADR-NNNN]"
- Link new ADR with "Supersedes [ADR-NNNN]"
- Update README.md index

### 6. ADR Review
Lightweight quality check using the `adr-critic` agent:
1. Read ADR at given path (if empty, ask — suggest globbing ADR dirs)
2. Spawn adr-critic agent (`subagent_type: "doc:adr-critic"`)
   - Pass: full ADR content
   - Instruct: "Read Author's Notes first as prioritized review targets"
3. Agent evaluates 4 dimensions, returns score + verdict + 3-5 findings
4. Present review to user
5. Verdicts: **Approve** | **Needs improvement** | **Needs rethink**
6. Suggest next steps based on verdict

### 7. Author's Notes (Confession)
Every ADR gets an `## Author's Notes` section after Consequences:
- **Shortcuts**: What was simplified or hand-waved?
- **Assumptions**: What was believed but not verified?
- **Uncertainties**: Which parts had least information?

Target: 2-5 items. Be specific, reference ADR sections.

**Lifecycle**: Added on create (always) | Read by adr-critic as review targets | Stripped when Status → Accepted (via `/adr status`) | Preserved on Superseded | Refreshed on major rewrites.

### 8. Status Transitions
Dedicated command for changing ADR status with validation and side effects:
1. Find ADR by number, read current status
2. Validate transition — warn on unusual paths (allow but confirm):
   - Accepted → Proposed: "Going backwards — re-opening a decided matter"
   - → Accepted without prior `/adr review`: "Consider reviewing first"
   - → Superseded directly: "Use `/adr supersede` to link replacement"
3. Apply status change, handle side effects:
   - **→ Accepted**: Strip `## Author's Notes` section entirely
4. Update README.md index via `adr_index.py`

**Valid statuses**: Proposed | Accepted | Deprecated | Superseded

## Core Template Sections

### Required (Minimal)
- **Status**: Proposed | Accepted | Deprecated | Superseded
- **Date**: ISO 8601 format (YYYY-MM-DD)
- **Context and Problem Statement**: 2-3 sentences describing the situation
- **Decision**: What was decided and why
- **Consequences**: Positive and negative impacts
- **Author's Notes**: Shortcuts, assumptions, uncertainties (stripped on Accepted)

### Optional Enhancements (MADR 4.0)
- **Technical Story**: Link to issue/spec (e.g., `#123`)
- **Decision Drivers**: Bulleted list of forces/concerns
- **Decision Makers**: Who made this decision
- **Consulted**: Stakeholders whose opinions were sought
- **Informed**: Stakeholders who need to know
- **Considered Options**: List of alternatives evaluated
- **Pros and Cons**: Detailed analysis per option
- **Confirmation**: How to validate the decision was implemented

## Quick Start

### Create New ADR
```bash
# Explicit subcommands:
/adr create Use PostgreSQL over MongoDB
/adr create Authentication approach for mobile apps

# Auto-invoke by saying:
"Document the decision to use PostgreSQL over MongoDB"
"Create an ADR for our authentication approach"
"I need to record why we chose React Query"
```

### Review an ADR
```bash
# Explicit subcommand:
/adr review docs/adr/0005-use-postgresql-for-persistence.md

# Auto-invoke:
"Review ADR-0005 for decision quality"
"Check if our caching ADR has solid reasoning"
```

### Supersede Existing ADR
```bash
# Explicit subcommand:
/adr supersede 5 12

# Auto-invoke:
"Supersede ADR-0005 with a new caching strategy"
"Replace our database decision ADR with the new approach"
```

### Change Status
```bash
# Transition with validation and side effects:
/adr status 14 accepted
/adr status 7 deprecated

# Auto-strips Author's Notes when accepting
# Warns on unusual transitions (e.g., skipping review)
```

### List and Index
```bash
/adr list
/adr index
```

## Scripts

Located in `${CLAUDE_SKILL_DIR}/scripts/` directory, using uv for execution:

### adr_create.py
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/adr_create.py --title "Use PostgreSQL for persistence"
uv run ${CLAUDE_SKILL_DIR}/scripts/adr_create.py --title "..." --template madr --create-dir
```

### adr_index.py
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/adr_index.py --dir docs/adr
uv run ${CLAUDE_SKILL_DIR}/scripts/adr_index.py --dir docs/adr --dry-run
```

### adr_supersede.py
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/adr_supersede.py --old 5 --new 12 --dir docs/adr
```

## Output Examples

### Proposed ADR (with Author's Notes)
```markdown
# ADR-0012: Use PostgreSQL for Data Persistence

## Status
Proposed

## Date
2026-01-10

## Context and Problem Statement
We need a reliable database solution for our microservices architecture
that supports complex queries and ACID transactions.

## Decision
Chosen option: PostgreSQL, because it provides the best balance of
ACID compliance, query flexibility, and team familiarity.

## Consequences
**Positive:**
- Full ACID transaction support
- Mature ecosystem and tooling

**Negative:**
- Horizontal scaling requires more setup

## Author's Notes
- **Shortcut**: Did not benchmark PostgreSQL vs CockroachDB under our expected write load; relied on team experience instead
- **Assumption**: Assumed read replicas will handle 5x current read traffic based on similar projects, not our actual query patterns
- **Uncertainty**: License compatibility of pgvector extension with our Apache 2.0 project not verified
```

### Accepted ADR (Author's Notes stripped)
```markdown
# ADR-0012: Use PostgreSQL for Data Persistence

## Status
Accepted

## Date
2026-01-10

(same content, but ## Author's Notes section removed entirely)
```

## Progressive Disclosure

- **Level 2**: [WORKFLOW.md](WORKFLOW.md) - Step-by-step methodology
- **Level 3**: [EXAMPLES.md](EXAMPLES.md) - Real-world ADR examples
- **Level 4**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Error handling

## Related Resources

- MADR 4.0 Template: https://adr.github.io/madr/
- ADR GitHub Organization: https://github.com/adr

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [joaquimscosta](https://github.com/joaquimscosta)
- **Source:** [joaquimscosta/arkhe-claude-plugins](https://github.com/joaquimscosta/arkhe-claude-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-joaquimscosta-arkhe-claude-plugins-adr
- Seller: https://agentstack.voostack.com/s/joaquimscosta
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.