adr-workflow

Files (2)

• SKILL.md
• adr.py

SKILL.md (first lines)

> 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.

```bash
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 helper routes on the current branch: on `main`
it runs the proven in-place flow (clean tree required); off `main` — a
feature branch or a linked `.claude/worktrees/*` worktree — it reserves
via an *ephemeral detached worktree* at `origin/main`, never touching
your branch, cwd, or working tree. No need to switch to `main` (a linked
worktree can't, anyway).

Flags:

- `--no-push` — commit locally only; skip fetch / push entirely. On
  `main` it commits on `main`; off `main` it commits a *provisional*
  reservation on the current branch (the number is local-view and may
  collide at merge — treat it as provisional). Pathspec-scoped, so
  unrelated staged work is not swept into the reservation commit.
- `--pr` — skip the direct-push attempt; go straight to branch + PR.
  Useful when you already know main is protection-locked. Mutually
  exclusive with `--no-push`.

Race-on-push (someone advanced `origin/main` while you were

From ramboz/jig, MIT.

More from ramboz/jig