/adr-workflow

name: adr-workflow
description: >
  Scaffold, accept, index, and link Architectural Decision Records (ADRs).
  Use when the user says "write an ADR", "record this decision", "resolve
  [deferred item] with an ADR", "supersede ADR-NNNN", or otherwise wants to
  capture a hard-to-reverse decision in `docs/decisions/`. Also use when a
  refinement-todo entry needs to be marked RESOLVED with a link back to the
  ADR. Do NOT use for ad-hoc design discussion that hasn't crystallized into
  a decision yet — wait until the choice is firm.
user-invocable: true

> Spec 005 created this skill from scratch. The mechanics live in `adr.py`; > Claude owns the judgment (what the decision actually says).

What this skill does

Codifies the ADR lifecycle that ADR-0001 and ADR-0002 were written by hand to exercise. Five deterministic operations:

• **`new`** — scaffold `docs/decisions/adr-NNNN-<slug>.md` from the template, with

auto-numbering and a slug-collision check. The scaffold carries `status: Proposed` in frontmatter (from the template) alongside the prose `Proposed (date)` line (spec 073-02 / ADR-0026).

• **`accept`** — stamp the canonical `status: Accepted` frontmatter field and

flip the prose Status line to `Accepted (YYYY-MM-DD)` in the **same** atomic write. Frontmatter is the authoritative status home; the prose line is a best-effort mirror, rewritten only when it is canonical (spec 073-02 / [ADR-0046](../../docs/decisions/adr-0046-adr-status-frontmatter-authority.md), which supersedes ADR-0026).

• **`supersede`** — append `Superseded by [ADR-NNNN](./adr-NNNN-<slug>.md) (date)`

to an Accepted ADR's Status block and `Supersedes ADR-NNNN` to the replacement's Status block, and stamp the **old** ADR's `status: Superseded` frontmatter field in the same atomic write (the replacement retains `status: Accepted`). This is the **one** edit allowed on an immutable ADR per the Nygard convention. Atomic write on both files.

• **`index`** — regenerate the `## Index` section of `docs/decisions/README.md`

from the actual ADR files present. Idempotent. The index is a **pure function of the ADR files**; see [section 4](#4-regenerate-the-index) for what that means for hand-edits and for records it cannot summarize.

• **`check-index`** — read-only audit of that index: exits non-zero if it no

longer matches the ADR files, or if two ADRs claim one number. Writes nothing.

• **`resolve-todo`** — strike through a `### Decision: ...` heading in

`docs/refinement-todo.md` and append `**Resolved by:** [ADR-NNNN: ...](...)`.

The script does file mutation deterministically. Claude is responsible for the prose inside the ADR (Context, Options Considered, Recommended Decision, Consequences, Open questions).

How to use

1. Author a new ADR

**Reference moved? Reframe first.** If this ADR is a reaction to a *load-bearing reference* changing from outside the system (a design system, vendor / API contract, test infra, compliance regime, platform, or product-positioning / strategic-vision shift), reach for `/jig:reframe` **before** hand-authoring — it drafts the keystone reframe-ADR (new reference authoritative, old premise superseded) + the re-baselining manifest for you, so the fallout is dispositioned rather than patched (spec 067 / [ADR-0024](../../docs/decisions/adr-0024-reference-reframe.md)).

**Step 0 — confirm the project is scaffolded (spec 066 / ADR-0011).** BEFORE reserving an ADR number or drafting ANY `docs/decisions/` structure, confirm this project is a scaffolded jig project. If it isn't, **route — do not hand-roll directories**:

• **Greenfield** (no jig structure yet) → tell the user to run

`/jig:scaffold-init`. It lays down conventions, templates, hooks, the status board, and the `docs/decisions/` tree (with its README).

• **Existing spec/`docs/decisions/` layout, but not jig-scaffolded** (no

`scaffold.json`) → tell the user to run `/jig:migrate`. It adopts the existing layout into jig structure.

You don't have to decide the state yourself: `adr.py new` (below) **classifies and routes** for you (spec 066-01) — a `scaffold.json`-bearing project proceeds; a greenfield project is refused naming `/jig:scaffold-init`; an adoptable spec-driven project is refused naming `/jig:migrate`. The deterministic gate and this human-readable precondition agree by construction, so **don't restate the detection heuristic here** — run the helper and let it route. (Bypass for a deliberate out-of-band flow: `JIG_SCAFFOLD_PRECONDITION=0`.)

**The anti-pattern this step exists to kill:** an auto-triggered `adr-workflow` run improvising a loose `docs/decisions/` skeleton (folder + README, or just dropping an `adr-NNNN-*.md` into a hand-made directory) because `/jig:scaffold-init` was skipped. That produces a non-jig layout that then needs migrating — the ADR-side of the reported failure. When in doubt, route to setup first; never invent the structure by hand.

python3 "${CLAUDE_PLUGIN_ROOT}/skills/adr-workflow/adr.py" new <slug> \
  [--title "<Title>"] [--project-dir DIR] [--no-push | --pr]

Run from the project root (the script looks for `./docs/decisions/`, or use `--project-dir DIR` to target a different root). The slug is kebab-case (`my-decision`). `--title` is optional — defaults to the title-cased slug.

**Reserve-on-origin/main is the default (slice 028-01).** The helper fetches `origin/main`, computes the next free `NNNN` from the just-fetched view, scaffolds the file, commits as `docs(decisions): reserve adr-NNNN-<slug>`, and pushes to `origin/main`. If the push is refused by branch protection / permissions, the helper automatically falls back to a `reserve/adr-NNNN-<slug>` branch + `gh pr create`. This locks the ADR number **team-wide** before any drafting begins, killing the parallel-worktree numbering-collision failure mode that motivated spec 028.

**Works from any branch or worktree** (ADR-0015 / spec 051, mirroring `workflow.py new`). The he