cc-os/plugins/os-adr/skills/create/SKILL.md

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

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.