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

# 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.