Adr Workflow

Spec 005 created this skill from scratch. The mechanics live in adr.py; Codex 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, 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 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. Codex 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).

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 "${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 .codex/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 reserving) surfaces as race-on-push: ... and drops the stranded local commit + the stranded ADR file from your working tree. Re-run the same adr.py new <slug> to pick the next free number — there is no auto-renumber.

Then Codex fills in Context / Options Considered / Recommended Decision / Consequences. Keep it tight: one decision per ADR.

2. Accept the ADR

Once the prose is settled and the human (or the workflow gate) approves:

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" accept <NNNN>

This stamps the canonical status: Accepted frontmatter field and flips the prose Proposed (date) line to Accepted (date) in the same atomic write (spec 073-02 / ADR-0046). Refuses if the ADR is already Accepted (ADRs are immutable; supersede instead — see below) or Superseded; the refusal names the state it found.

Prose is best-effort (ADR-0046). The state that gates the flip is read from the frontmatter status: field, falling back to a lenient prose classifier for legacy ADRs — never from the prose formatting. A hand-edited or decorated Status line such as

Proposed (2026-07-22) — awaiting owner acceptance.

no longer blocks accept. The frontmatter flips; the authored line is left exactly as written (never truncated, never rewritten into a self-contradictory Accepted (…) — awaiting owner acceptance), and accept prints a note on stderr naming the file and the value the prose should carry. Reconciling that line is your job — deterministic tooling does not rewrite prose it cannot fully parse. Until you do, frontmatter and prose are briefly out of step; every reader in adr.py is frontmatter-first, so the divergence is cosmetic, not behavioural.

Frame-critique gate (spec 064-05 / ADR-0020 OQ2/OQ3). accept also gates the flip on a passing adversarial frame-critique verdict — the ADR's pre-commitment moment to catch a wrong premise (the ADR-0011 / ADR-0008 failure mode). It applies iff the ADR carries a truthy frame_review flag: new stamps frame_review: true on every ADR it creates (OQ3 — ADRs always-on), so new ADRs are gated; a legacy markerless Proposed ADR is grandfathered (no refusal). To clear it: build the prompt with review.py frame-critique docs/decisions/adr-NNNN-*.md, run a reviewer, then review.py record-review --adr NNNN --pass frame-critique --verdict pass … (writes docs/decisions/reviews/adr-NNNN-frame-critique.md). Soft / bypassable with JIG_REVIEW_EVIDENCE_GATE=0 (a deliberateness signal, ADR-0011 — not human-only enforcement).

3. Supersede an Accepted ADR

When a previously-Accepted decision is replaced by a newer one, don't edit the old ADR's prose — write a new ADR (per new above), accept it, then run:

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" \
  supersede <old-NNNN> <new-NNNN>

Both ADRs must already be Accepted. The helper:

• appends Superseded by [ADR-<new>](./adr-<new>-<slug>.md) (today) to the old ADR's ## Status block,
• appends Supersedes ADR-<old> (plain text, no link, no date) to the new ADR's ## Status block,
• preserves both Accepted (date) lines (this is the one edit allowed on an immutable ADR per the Nygard convention),
• stamps the old ADR's status: Superseded frontmatter field in the same atomic write (the replacement keeps status: Accepted) — spec 073-02 / ADR-0026, so a dependency on a superseded ADR correctly fails,
• writes both files atomically.

Refuses (exit 2) if either ADR is Proposed (accept it first), if either ADR is already Superseded, if <old> == <new> (self-supersession), or if either NNNN is malformed. State is read frontmatter-first, as for accept.

Unlike accept, supersede also refuses when an ADR is Accepted but its prose ## Status carries no canonical Accepted (YYYY-MM-DD) line: the supersession lines are inserted after that anchor and are load-bearing, so there is no best-effort path — put the Status line in canonical form and re-run (ADR-0046 ruling 5). The refusal happens before either file is written, and it checks both ADRs. Re-run adr.py index docs/decisions after to refresh the index entries.

Writing that canonical line needs the acceptance date, and a diverged ADR does not hold it: the prose date belongs to the pre-acceptance state, and frontmatter last_verified is a freshness field (/jig:reframe's reaffirm disposition refreshes it), not an acceptance date. The refusal prints the git log invocation that recovers the date from the accept commit — use that rather than the metadata. Reconciling the prose when accept first warns about it avoids this entirely.

4. Regenerate the index

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" index docs/decisions

Reads every adr-NNNN-*.md (skipping README.md) and rewrites only the ## Index section of docs/decisions/README.md. Everything else in the README (header, format spec, "When to write" section) is preserved. Re-running on a current README is a no-op.

The Index section is derived, never hand-edited. Each bullet's summary is generated from that ADR's ## Context opening, so a better sentence written straight into the README is overwritten on the next regen. If a row reads badly, fix the ADR's opening paragraph — that is the summary's source.

When there is nothing to derive, index says so instead of inventing. A summary needs a complete sentence to come from. Three openings have none: a lead-in to a list or a table (the common one), a paragraph that simply lacks a final period, and a record still carrying the template's _TODO stub. Each renders as (no description) with a warning on stderr naming the record and the reason (bug 020). Before that, the lead-in was written out verbatim — colon and all — or cut at 120 characters with a trailing …, which read like a summary and was not one:

adr.py index: ADR-0040 (adr-0040-richer-skill-discovery-explicit-candidate-channel.md)
  — its `## Context` is still the template stub; rendering (no description).
adr.py index: reword each record's `## Context` opening into a standalone
  sentence and re-run. The index is derived from the ADR files, so the fix
  belongs at the source, not in README.md.

The remedy is the one ADR-0006 already prescribes: reword the opening into a standalone sentence and keep the list behind it. index exits 0 either way — this is a report, not a gate.

A record with nothing written in it is meant to keep warning. ADR-0040 on main is a template stub in every section; (no description) is the honest line for it and the warning is the reminder that it is unwritten. Do not invent decision prose to silence it — write the decision, or leave it.

An authored trailing … is not truncation and is left alone: jig no longer emits one, so an ellipsis in a summary is the author's own writing.

Audit the index before landing. check-index is a read-only companion to index:

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" \
  check-index docs/decisions

Exits non-zero on either problem it can find. Stale index — an ADR changed and index wasn't re-run (or a summary was hand-edited). Duplicate ADR number — two ADRs claim one number, which is what parallel branches produce when the number was never reserved on the trunk. The index renders both bullets without complaint and a staleness check can't see it (both are faithfully derived), so it needs its own detector; the message names both files so you know which to renumber.

5. Resolve a deferred decision

If the new ADR resolves a ### Decision: ... entry in docs/refinement-todo.md:

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" \
  resolve-todo <NNNN> "<heading fragment>"

The fragment is a case-insensitive substring (same lenient style as workflow.py's slice fragment). The helper:

• wraps the heading line in ~~strikethrough~~,
• appends — RESOLVED YYYY-MM-DD,
• wraps the first **Deferred:** line in strikethrough,
• appends a **Resolved by:** [ADR-NNNN: ...](decisions/adr-...) line at the end of the section.

Refuses (exit 2) if the fragment is ambiguous, the section is already struck through, or the ADR hasn't been Accepted yet.

Immutability rule

Never edit an Accepted ADR. The Nygard convention treats ADRs as historical record — if the decision changes, write a new ADR that supersedes the old one. The supersession lines (one on each side) are the only edit allowed on an immutable ADR. Use the supersede subcommand (section "3. Supersede an Accepted ADR" above) — adr.py supersede <old-NNNN> <new-NNNN> writes those lines deterministically on both ADRs and refuses self-supersession, Proposed-ADR inputs, or double-supersession.

What the helper does (so you can spot-check the result):

1. Old ADR's ## Status block gains a line appended after the existing Accepted (date) line: Superseded by [ADR-<new>](./adr-<new>-<slug>.md) (today).
2. New ADR's ## Status block gains a plain-text line after its Accepted (date): Supersedes ADR-<old> (no link, no date).
3. Both Accepted (date) lines are preserved.

If a user asks to "supersede ADR-NNNN", route them to the supersede subcommand — both ADRs must already be Accepted; if the replacement isn't drafted yet, walk them through new + accept for the new ADR first.

End-to-end example (full lifecycle)

The canonical lifecycle is new → edit → index (preview) → accept → index (final). The preview-index pass surfaces a truncated or ugly first-bullet line while the ADR is still mutable (per ADR-0006). Skip the preview only if the Context first sentence is known to be index-friendly (no abbreviations outside the helper's allowlist, fits in one short clause).

# 1. Identify the deferred decision in docs/refinement-todo.md.
#    Fragment: "scaffold-stable" (matches "### Decision: scaffold-stable …").

# 2. Scaffold the ADR.
python3 .../adr.py new scaffold-stable --title "scaffold-stable trigger"
# → docs/decisions/adr-0003-scaffold-stable.md

# 3. Codex edits the file: fills Context, Options, Recommended, Consequences.

# 4. Preview the index BEFORE accept, while the ADR is still mutable.
python3 .../adr.py index docs/decisions
# Inspect the new bullet line. If it looks wrong (truncated mid-
# abbreviation, missing the key noun, etc.), edit the ADR's first
# Context sentence and re-run this command. Iterate freely.

# 5. Accept.
python3 .../adr.py accept 0003
# → flips Proposed → Accepted (today).

# 6. Final index regen (idempotent re-run; updates only the Accepted line).
python3 .../adr.py index docs/decisions

# 7. Mark the refinement-todo entry resolved.
python3 .../adr.py resolve-todo 0003 "scaffold-stable"

Boundary-change nudge

A PostToolUse hook (jig-boundary-change-warn) fires on Edit/Write/MultiEdit of a canonical external-interface contract-artifact file (OpenAPI openapi.yaml/.yml/.json, AsyncAPI asyncapi.yaml/.yml/.json, *.proto, *.graphql/*.graphqls, or *.schema.json). It emits a soft additionalContext nudge pointing the author at /jig:adr-workflow new <slug> (capture the rationale if the change is breaking) plus the surface-appropriate breaking-change ecosystem tool (buf breaking, graphql-inspector diff, redocly diff / spectral, AsyncAPI parser diff, JSON-Schema diff). The nudge is informational, never a gate — set JIG_BOUNDARY_CHECK=0 to silence it. The filename + tool list is sourced manually from the contracts skill's per-surface table; the contracts skill is the source of truth for which artifact governs which surface.

Gotchas

• Auto-numbering does not fill gaps. If 0001 and 0003 exist (no 0002), the next new ADR is 0004. The gap is preserved as historical record.
• Slug collisions refuse regardless of number. adr-0001-foo.md exists → adr.py new foo exits 2. Either pick a different slug or write a superseding ADR.
• resolve-todo touches only three lines. Heading, first **Deferred:** line, and one new **Resolved by:** line appended at the section end. Other fields (**Resolution trigger:**, **Mitigation idea:**, **Watch-list:**, etc.) are left intact. If a section needs more intricate updates, edit it by hand.
• Index description extraction may produce ugly first lines. The helper takes the first non-empty paragraph from ## Context, truncating at the first sentence-ending punctuation when the paragraph is multi-line, runs past 120 chars, or ends in a colon. When it has no complete sentence at all, see section 4 — the bullet gets (no description) and a warning. Common abbreviations (e.g., i.e., etc., Mr., Dr., …) are skipped by an explicit allowlist; abbreviations outside that list may still cause a mid-word cut. If the resulting bullet reads oddly, edit the ADR's first Context sentence to be index-friendly. Per ADR-0006, edits to Context-section prose to fix index-rendering are NOT decision-content and do not violate the immutability rule. Edits to Status, Recommended Decision, or Consequences DO violate immutability and require a superseding ADR. Run index BEFORE accept as a preview pass to catch this while the ADR is still freely mutable.
• The helper does NOT spawn a Task or commit anything. It only mutates files. Codex is responsible for orchestration (e.g. running workflow.py status-board afterward, writing commit messages, invoking the reviewer subagent).
• Substring matching mirrors workflow.py. 0001-01 does not collide with 0001 since ADR numbers are matched as exact 4-digit prefixes, not free-form substrings (unlike slice fragments).
• adr.py new is worktree-aware (ADR-0015 / spec 051). It routes on the current branch: on main it runs the proven 028-01 in-place flow (clean tree required); off main — a feature branch or a linked worktree — it reserves via an ephemeral detached worktree at origin/main (push mode) or commits a provisional reservation on the current branch (--no-push), without disturbing your branch or tree. You no longer need to git checkout main first (and a linked worktree can't, since the primary worktree holds main). The earlier off-main/dirty-tree refusal — and its impossible git checkout main workaround — is gone.

Reconciliation checklist

After using this skill in a real session:

• Did the index regen produce sensible descriptions, and did it warn about any record it could not summarize? For a written record, reword its first Context paragraph into a standalone sentence and re-run adr.py index — the index is derived, so the fix belongs at the source. For an unwritten stub, leave the warning: it is the reminder.
• Was the refinement-todo entry actually resolved by this ADR, or did a partial overlap make resolve-todo apply to the wrong section? Verify before committing.
• Did the human approve the Recommended Decision before accept? If not, walk back to the Proposed state by editing the Status line (this is the one situation where editing a not-yet-Accepted ADR is fine — it's not yet immutable).