# Adr

> Tracks Architecture Decision Records (ADRs) in docs/adrs/. Creates, lists, and updates ADRs following project conventions. TRIGGER when: user wants to record, review, or update an architectural decision.

- Skill: `apocohq/adr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add apocohq/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apocohq/adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: apocohq (https://skillmd.com/u/apocohq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apocohq/adr

---


# ADR Tracking

Manage Architecture Decision Records in `docs/adrs/`. Interpret `$ARGUMENTS` as natural language.

## Creating an ADR

Ask the user for any missing information. You need at minimum: title, context, decision, and owner (@github-username).

If the decision is made → create `docs/adrs/NNN-short-title.md` with status `Accepted`.
If the decision is open → create `docs/adrs/DRAFT-short-title.md` with status `Proposed`.

Assign the next number by reading `docs/adrs/index.md`. Always update the index after creating a file.

## Updating an ADR

Valid status transitions: `Accepted`, `Deprecated`, `Superseded by ADR-NNN`.

When promoting a Draft to Accepted: rename `DRAFT-title.md` → `NNN-title.md` and move the row from Drafts to Accepted in the index.

## Conventions

- **Accepted**: `NNN-short-title.md` — numbered, zero-padded to 3 digits, never reused
- **Drafts**: `DRAFT-short-title.md` — no number until accepted
- **Owner**: the person accountable for the decision — drives it to resolution, revisits if context changes
- File names: short kebab-case, 2-3 words max
- Index: `docs/adrs/index.md` — always keep in sync

## Template

```markdown
# ADR-NNN: Title

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Owner:** @github-username

## Context

What is the issue motivating this decision?

## Decision

What we decided.

## Alternatives Considered

What else was evaluated and why rejected.

## Consequences

What becomes easier or more difficult.
```