ADR Records skill for Claude Code

#!/usr/bin/env python3
"""Create, list, and check Architecture Decision Records (MADR-style Markdown).

Usage:
  python3 scripts/adr.py new "Use PostgreSQL for the event store" [--dir docs/adr] [--supersedes 7]
  python3 scripts/adr.py list [--dir docs/adr]
  python3 scripts/adr.py check [--dir docs/adr]

Without --dir, the first existing of docs/adr, docs/decisions, doc/adr, adr is used
(docs/adr is created for `new` if none exists).

ADR files are named NNNN-title-in-kebab-case.md. Status is read from YAML front matter
(`status: accepted`) or from a Nygard-style `## Status` section.

Exit codes: 0 = ok, 1 = check found problems or a referenced ADR is missing.
"""
import argparse
import datetime as dt
import os
import re
import sys

CANDIDATE_DIRS = ["docs/adr", "docs/decisions", "doc/adr", "adr"]
VALID = re.compile(r"^(proposed|accepted|rejected|deprecated|superseded by .+)$", re.I)
NAME = re.compile(r"^(\d{4})-([a-z0-9-]+)\.md$")

TEMPLATE = """---
status: {status}
date: {date}
decision-makers: {{list who decided}}
consulted: {{optional}}
informed: {{optional}}
---

# {title}

## Context and Problem Statement

{{Describe the situation and the question being decided in 2-5 sentences. Link the issue,
incident, or design doc that triggered it.}}

## Decision Drivers

* {{driver, e.g. p95 latency under 200 ms at 3k req/s}}
* {{driver, e.g. team already operates PostgreSQL}}

## Considered Options

* {{option 1}}
* {{option 2}}
* {{option 3, including "do nothing" when realistic}}

## Decision Outcome

Chosen option: "{{option}}", because {{justification tied to the drivers}}.
{supersedes}
### Consequences

* Good, because {{positive consequence}}
* Bad, because {{negative consequence or accepted cost}}

### Confirmation

{{How compliance is checked: a lint rule, a fitness function, a review checklist item,
a load test result.}}

## Pros and Cons of the Options

### {{option 1}}

* Good, because {{...}}
* Bad, because {{...}}

### {{option 2}}

* Good, because {{...}}
* Bad, because {{...}}

## More Information

{{Links, revisit trigger (e.g. "revisit if write volume exceeds 5k/s"), related ADRs.}}
"""


def find_dir(explicit, create):
    if explicit:
        if create:
            os.makedirs(explicit, exist_ok=True)
        return explicit
    for d in CANDIDATE_DIRS:
        if os.path.isdir(d):
            return d
    if create:
        os.makedirs(CANDIDATE_DIRS[0], exist_ok=True)
        return CANDIDATE_DIRS[0]
    print("error: no ADR directory found (looked for " + ", ".join(CANDIDATE_DIRS) + ")", file=sys.stderr)
    sys.exit(1)


def adrs(directory):
    out = []
    for f in sorted(os.listdir(directory)):
        m = NAME.match(f)
        if m:
            out.append((int(m.group(1)), f))
    return out


def slugify(title):
    s = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
    return re.sub(r"-{2,}", "-", s)[:60].rstrip("-")


def read_meta(path):
    text = open(path, encoding="utf-8").read()
    status = None
    fm = re.match(r"^---\n(.*?)\n---\n", text, re.S)
    if fm:
        m = re.search(r"^status:\s*(.+)$", fm.group(1), re.M)
        if m:
            status = m.group(1).strip().strip('"')
    if status is None:
        m = re.search(r"^##\s*Status\s*\n+\s*(.+)$", text, re.M | re.I)
        if m:
            status = m.group(1).strip()
    tm = re.search(r"^#\s+(.+)$", text, re.M)
    title = tm.group(1).strip() if tm else "(no title)"
    return text, status, title


def set_status(path, new_status):
    text = open(path, encoding="utf-8").read()
    fm = re.match(r"^---\n(.*?)\n---\n", text, re.S)
    if fm and re.search(r"^status:", fm.group(1), re.M):
        body = re.sub(r"^status:.*$", f"status: {new_status}", fm.group(1), count=1, flags=re.M)
        text = f"---\n{body}\n---\n" + text[fm.end():]
    elif re.search(r"^##\s*Status\s*\n+\s*.+$", text, re.M | re.I):
        text = re.sub(r"(^##\s*Status\s*\n+\s*).+$", lambda m: m.group(1) + new_status, text, count=1, flags=re.M | re.I)
    else:
        return False
    open(path, "w", encoding="utf-8").write(text)
    return True


def cmd_new(args):
    d = find_dir(args.dir, create=True)
    existing = adrs(d)
    num = (existing[-1][0] + 1) if existing else 1
    fname = f"{num:04d}-{slugify(args.title)}.md"
    path = os.path.join(d, fname)
    sup_line = ""
    old_path = None
    if args.supersedes is not None:
        match = [f for n, f in existing if n == args.supersedes]
        if not match:
            print(f"error: ADR {args.supersedes:04d} not found in {d}", file=sys.stderr)
            sys.exit(1)
        old_path = os.path.join(d, match[0])
        sup_line = f"\nSupersedes [ADR-{args.supersedes:04d}]({match[0]}).\n"
    content = TEMPLATE.format(status=args.status, date=dt.date.today().isoformat(),
                              title=args.title, supersedes=sup_line)
    with open(path, "x", encoding="utf-8") as fh:
        fh.write(content)
    print(f"created {path}")
    if old_path:
        if set_status(old_path, f"superseded by [ADR-{num:04d}]({fname})"):
            print(f"updated status of {old_path}")
        else:
            print(f"warn: could not find a status line in {old_path}; update it by hand", file=sys.stderr)


def cmd_list(args):
    d = find_dir(args.dir, create=False)
    for num, f in adrs(d):
        _, status, title = read_meta(os.path.join(d, f))
        shown = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", status or "?")
        print(f"{num:04d}  {shown[:28]:28}  {title}")


def cmd_check(args):
    d = find_dir(args.dir, create=False)
    problems = []
    seen = {}
    names = {f for _, f in adrs(d)}
    for num, f in adrs(d):
        if num in seen:
            problems.append(f"duplicate number {num:04d}: {seen[num]} and {f}")
        seen[num] = f
        _, status, title = read_meta(os.path.join(d, f))
        if not status:
            problems.append(f"{f}: no status")
        elif not VALID.match(status):
            problems.append(f"{f}: invalid status '{status}'")
        elif status.lower().startswith("superseded"):
            link = re.search(r"\(([^)]+\.md)\)", status)
            if not link or link.group(1) not in names:
                problems.append(f"{f}: superseded but link to the new ADR is missing or broken")
        if title == "(no title)":
            problems.append(f"{f}: no '# Title' heading")
    for f in os.listdir(d):
        if f.endswith(".md") and not NAME.match(f) and f.lower() not in ("readme.md", "index.md", "template.md"):
            problems.append(f"{f}: name does not match NNNN-kebab-title.md")
    for p in problems:
        print("PROBLEM", p)
    print(f"{len(seen)} ADR(s) checked, {len(problems)} problem(s)")
    sys.exit(1 if problems else 0)


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = ap.add_subparsers(dest="cmd", required=True)
    n = sub.add_parser("new")
    n.add_argument("title")
    n.add_argument("--dir")
    n.add_argument("--status", default="proposed")
    n.add_argument("--supersedes", type=int)
    for name in ("list", "check"):
        s = sub.add_parser(name)
        s.add_argument("--dir")
    args = ap.parse_args()
    {"new": cmd_new, "list": cmd_list, "check": cmd_check}[args.cmd](args)


if __name__ == "__main__":
    main()