---
description: Record an architecture decision as a correctly templated, numbered, and indexed ADR in one invocation. Use when a decision of real consequence (irreversible, cross-cutting, contested, or convention-setting) has just been made or is being made — including unprompted, when you recognize such a decision mid-task. Invoked by `/os-adr:create`.
---

Create a new ADR under `docs/adr/`. All mechanical work (ID assignment, templating, index
regeneration, supersession bookkeeping) is done by the plugin's CLI — never hand-author the
file, number, or index.

## 1. Gather the decision content

From the conversation (ask only for what you cannot infer):

- **title** — short, imperative or noun-phrase ("Use Postgres for persistence")
- **context** — the forces/problem that made a decision necessary
- **decision** — what was decided, stated actively
- **consequences** — what becomes easier/harder as a result
- **alternatives** — options considered and *why each was rejected* (highest-value field; push
  for real reasons, not placeholders)
- **affected_paths** / **affected_components** — repo paths and component names this decision
  governs (used for deterministic retrieval later; be concrete, e.g. `["src/db/", "config/database.yml"]`)
- **status** — default `Accepted`; use `Proposed` only if the user says it isn't settled
- **supersedes** — 4-digit ID, only if this replaces an existing ADR (check `docs/adr/README.md`)

If the project has no `docs/adr/` yet, run `/os-adr:init` first (or its CLI, step 2's
`adr-init`).

## 2. Invoke the CLI

```bash
echo '{"title": "...", "context": "...", "decision": "...", "consequences": "...",
  "alternatives": "...", "affected_paths": ["..."], "affected_components": ["..."]}' \
  | ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-new --root <project-root>
```

Optional JSON fields: `status`, `date` (ISO), `supersedes` ("NNNN"). The CLI prints the created
file path, sets `superseded-by` + `Superseded` status on any superseded ADR, and regenerates
`docs/adr/README.md`. Prefer writing the JSON to a temp file and piping it (`cat file | ...`)
when section bodies contain quotes.

## 3. Confirm

Show the user the created path and a one-line summary. Do not edit the generated index by hand.