adr

Author a numbered, dated, user-attributed Architecture Decision Record under .codearbiter/decisions/.

What it does

Records an architectural decision as a numbered, dated ADR under .codearbiter/decisions/. This is the only sanctioned way an ADR gets written: the underlying skill drops a 30-minute authoring marker immediately before the write, and the repo’s pre-write/pre-edit hooks refuse to touch a .codearbiter/decisions/NNNN-*.md file without one. Status transitions (proposed → accepted → superseded | rejected) always require your explicit instruction — the decision never advances on its own.

Usage

/ca:adr "<decision title>"

Title the decision as what was decided, not what was considered — "Use PostgreSQL as the primary database", not "Database selection".

Example

> /ca:adr "Use PostgreSQL as the primary database"

Indexed 6 existing ADRs under .codearbiter/decisions/ — next number is 0007.

Confirm before I write:
  Context: <you supply/confirm>
  Decision: Use PostgreSQL as the primary database
  Alternatives considered: <you supply/confirm>
  Consequences: <you supply/confirm>

Written: .codearbiter/decisions/0007-use-postgresql-as-the-primary-database.md (status: proposed)
Decision log entry appended — Decided by: dev@example.com

When to reach for it

Recording a decision you’ve already made. If the question is which option to pick, that’s /ca:reconcile; if you just want to know an ADR’s health, that’s /ca:adr-status.

Gates

Gate	When	Effect
user attribution	authoring the ADR content	context, decision, alternatives, and consequences are confirmed with you directly — an unknown becomes an inline `[CONFIRM-NN]`, never a guess
numbering + marker	writing the file	the next ADR number is fixed with no gap, and a short-lived authoring marker is armed so the write hooks allow the file — `/adr` is the only path that can arm it

Source

Source — plugins/ca/commands/adr.md (v2.9.1)

---
description: Author a numbered, dated, user-attributed Architecture Decision Record under .codearbiter/decisions/.
argument-hint: "<decision title>"
---

# /ca:adr — author an ADR

Record an architectural decision as a numbered, dated ADR. Title the decision clearly — name what was
decided, not what was considered (`"Use PostgreSQL as the primary database"`, not
`"Database selection"`). This is the only sanctioned path to author an ADR.

## Routes to

The `decision-lifecycle` skill (`${CLAUDE_PLUGIN_ROOT}/skills/decision-lifecycle/SKILL.md`). The skill
owns numbering, the file template, the `proposed → accepted → superseded | rejected` status lifecycle,
and writes the file to `${CLAUDE_PROJECT_DIR}/.codearbiter/decisions/`. Status transitions require
explicit user instruction; the orchestrator never advances an ADR on its own.

## When NOT to use

- Check the health of existing ADRs → `/ca:adr-status`.
- Reconcile or challenge a suspect ADR → `/ca:reconcile`.
- Ask about a decision without recording it → `/ca:btw`.

## Hard gate

An ADR is authored ONLY via `/ca:adr` with explicit user attribution. MUST NOT author an ADR as the
disposition of a routine finding — decision-worthy findings surface to the user or to
`open-questions.md` as a `[CONFIRM-NN]`. MUST NOT resolve a `[CONFIRM-NN]` in the ADR by guessing.

View in repo

adr