44 lines
2.2 KiB
Markdown
44 lines
2.2 KiB
Markdown
---
|
|
name: create
|
|
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.
|