# api-design-review

Adopt this skill: https://proskills.md/skills/other/dotslashsimran-simcraft-skills-coding-api-design-review

Page: https://proskills.md/skills/other/dotslashsimran-simcraft-skills-coding-api-design-review
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/coding/api-design-review/SKILL.md
size: 6925
sha: f3c182cf42401c17e13386ffed7639cdc539720e
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/SKILL.md

````text
---
name: api-design-review
description: Review the design of an API surface, meaning an HTTP API (OpenAPI spec or route code), an SDK's public classes and functions, or a CLI. Checks naming and consistency, resource modelling, error design (stable codes, RFC 9457 problem details, request ids), versioning and breaking changes, pagination, filtering, idempotency and retries, rate limits, timeouts, long-running operations, webhooks, auth, partial updates, ID, time and money formats, SDK ergonomics and CLI conventions. Uses scripts to lint OpenAPI files, classify changes between two spec versions as breaking or safe, and dump an SDK's public surface. Writes review.md with a scorecard, ranked findings with rewrites, a breaking-change risk list and what is good. Use when the user says "review my API", "API design", "is this a breaking change", "OpenAPI review", "check my spec", "SDK ergonomics", "review my SDK", "review my CLI", or asks whether an API change is safe to ship. For onboarding and time to first success, use dx-audit instead.
---

# API design review

This skill reviews the shape of an API, which is the names, resources, errors, formats and rules that every user has to learn. Most API design mistakes are cheap to fix before launch and expensive after it, because fixing them breaks clients. The review therefore puts the findings that would be breaking to fix later at the top.

The judgement lives in `reference.md`, which has the scoring rubric, the severity scale, the rules for each area with citations to public guidelines (Google AIP, Microsoft REST API Guidelines, Stripe's API conventions, Zalando RESTful API Guidelines, IETF RFCs), and before and after rewrites. Read the sections that match the API before writing findings.

The scripts need only Python 3.9 or newer and the standard library. They read JSON, and they read YAML with PyYAML if it is installed or with a small built-in parser if it is not. Files that use YAML anchors or tags need PyYAML or a JSON copy.

## 1. Find out what to review

Ask one question at a time, and only for what is missing:

- **What is the surface?** It can be an OpenAPI file, route code, an SDK (a Python package name or a `.d.ts` file), or a CLI (`--help` output or the command source).
- **Who uses it?** Public, partner, or internal with one client. This sets severity (reference.md section 2).
- **Is it launched?** Before launch, recommend breaking fixes freely. After launch, every fix must come with a migration path.
- **Is there an old version to compare against?** If yes, run the diff in step 3.

## 2. Run the tools

Set `S=~/simcraft/skills/coding/api-design-review/scripts`.

**OpenAPI lint:**
```
python3 $S/lint_openapi.py openapi.yaml            # text
python3 $S/lint_openapi.py openapi.yaml --format md
python3 $S/lint_openapi.py openapi.yaml --fail-on high   # exit 1 for CI
```
It checks path and field case consistency, plural collections, verbs in paths, error schemas (missing, inconsistent, no machine code, no request id), undocumented 4xx and 5xx, list endpoints with no pagination or a bare array response, mixed ID and time formats, money as floats, creating POSTs without an Idempotency-Key, PATCH bodies with required fields, 429 without Retry-After, duplicate or missing operationIds, and unsigned webhooks.

**SDK surface:**
```
python3 $S/sdk_surface.py my_package [--path src] [--depth 2]
python3 $S/sdk_surface.py dist/index.d.ts
```
It prints the public tree (modules, classes, signatures, properties, constants) and hints about boolean flag arguments, long positional parameter lists, mutable defaults, `any`, optional parameters before required ones, timeouts that default to waiting forever, error classes with no common base, and missing docs. Importing a Python package runs its import code, so only run it on code the user trusts.

**For a CLI**, there is no script. Run `<tool> --help` and the help for each subcommand, try one command with `--json` and with output piped to a file, check the exit code after a failing command (`echo $?`), and compare against reference.md section 17.

**For route code with no spec**, export a spec if the framework can (reference.md section 18). Otherwise build the endpoint list by reading the routes.

The scripts find patterns, and they also produce false positives. Read every finding, drop the ones that are wrong for this API, and say which areas the scripts cannot check (behaviour, defaults, docs quality, real latency).

## 3. Check breaking changes

When there are two versions:
```
python3 $S/breaking_diff.py old.json new.yaml [--format md]
```
It sorts every change into BREAKING, RISKY or SAFE, says why, shows where changed shared schemas are used, and says what semver bump the changes need. It exits 1 if anything is breaking, so it can run in CI on every pull request.

The script cannot see behaviour changes such as a new default value, a different sort order, stricter server-side validation that the spec does not show, or new side effects. Ask about those directly.

When there is only one version, write the breaking-change risk list from the lint instead. It lists the findings whose fix would itself be breaking (bare array lists, integer IDs, missing pagination, error shape, field renames), so the user knows what to fix before launch.

## 4. Write review.md

Write `review.md` next to the API source unless the user says otherwise. Use this structure, and see `examples/review.md` for a full example:

1. **Summary.** Two or three sentences with the overall verdict and the top three fixes.
2. **Scorecard.** A table with each area from the reference.md rubric, a 0 to 3 score, and one line of reason. Mark areas that do not apply as n/a.
3. **Findings, ranked by severity (P0 to P3).** For each finding, give where it is, what is wrong, why it costs users something, the precedent from a public guideline, and a concrete rewrite (before and after for the path, schema, error body or call site). Group repeated cases into one finding with a list of locations.
4. **Breaking-change risk list.** Diff results if there were two versions. Otherwise, the fixes from the findings that would break clients, each with a migration path (alias, deprecation header, sunset date, new version).
5. **What's good.** Specific things the API does well, so the team keeps doing them. Write this section honestly and specifically, with no padding.
6. **Not checked.** What the review could not see.

Keep findings concrete. "Errors are inconsistent" is not a finding. "`POST /orders` returns `{error: {msg}}` and `GET /orders/{id}` returns `{message}`, so clients need two error handlers" is a finding.

## 5. Hand over

Show the user the summary and the top findings in chat, and give the path to `review.md`. If they want to fix things, start with the P0 findings, then the P1 findings that are breaking, and re-run the lint and the diff after each change.
````

## File: skills/coding/api-design-review/scripts/_spec.py
size: 10764
sha: a0858e94e473364adf0e9db47886c43ad57dd5c7
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/scripts/_spec.py

```text
"""Shared helpers: load an OpenAPI document (JSON or YAML) and resolve local $refs.

Standard library only. If PyYAML is installed it is used for YAML files.
Otherwise a small fallback parser handles the block-style YAML subset that
OpenAPI files normally use (maps, lists, quoted and plain scalars, flow lists
and maps on one line, | and > block strings, comments). Anchors, aliases,
tags and multi-document files are not supported by the fallback; convert
those files to JSON first.
"""

import json
import re
import sys

HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")

# ---------------------------------------------------------------- loading

def load_spec(path):
    with open(path, "r", encoding="utf-8") as fh:
        text = fh.read()
    stripped = text.lstrip()
    if stripped.startswith("{"):
        return json.loads(text)
    try:
        import yaml  # type: ignore
        return yaml.safe_load(text)
    except ImportError:
        pass
    try:
        return MiniYaml(text).parse()
    except Exception as exc:  # noqa: BLE001
        sys.exit(
            "Could not parse %s as YAML without PyYAML (%s).\n"
            "Install PyYAML (pip install pyyaml) or convert the file to JSON." % (path, exc)
        )

class MiniYaml:
    """Minimal block-YAML parser, enough for typical OpenAPI files."""

    def __init__(self, text):
        self.lines = []
        raw = text.splitlines()
        i = 0
        while i < len(raw):
            line = raw[i].rstrip()
            i += 1
            if not line.strip() or line.strip().startswith("#") or line.strip() in ("---", "..."):
                continue
            indent = len(line) - len(line.lstrip(" "))
            content = _strip_comment(line.strip())
            self.lines.append([indent, content, i])
            # keep raw lines of block scalars untouched
            if re.search(r":\s*[|>][-+]?$", content) or re.match(r"^-\s*[|>][-+]?$", content):
                block = []
                while i < len(raw) and (not raw[i].strip() or
                                        len(raw[i]) - len(raw[i].lstrip(" ")) > indent):
                    block.append(raw[i])
                    i += 1
                self.lines[-1].append(block)

    def parse(self):
        if not self.lines:
            return None
        value, idx = self._block(0, self.lines[0][0])
        if idx != len(self.lines):
            raise ValueError("unexpected indentation at line %d" % self.lines[idx][2])
        return value

    def _block(self, idx, indent):
        if self.lines[idx][1].startswith("- ") or self.lines[idx][1] == "-":
            return self._list(idx, indent)
        return self._map(idx, indent)

    def _list(self, idx, indent):
        out = []
        while idx < len(self.lines) and self.lines[idx][0] == indent and (
                self.lines[idx][1].startswith("- ") or self.lines[idx][1] == "-"):
            entry = self.lines[idx]
            rest = entry[1][1:].strip()
            if not rest:
                idx += 1
                if idx < len(self.lines) and self.lines[idx][0] > indent:
                    val, idx = self._block(idx, self.lines[idx][0])
                else:
                    val = None
                out.append(val)
            elif _split_key(rest) is not None and not rest.startswith(("'", '"', "[", "{")):
                # "- key: value" starts a map indented at the key position
                offset = len(entry[1]) - len(rest)
                entry[0] = indent + offset
                entry[1] = rest
                val, idx = self._map(idx, indent + offset)
                out.append(val)
            elif len(entry) > 3:
                out.append(_block_scalar(rest, entry[3]))
                idx += 1
            else:
                out.append(_scalar(rest))
                idx += 1
        return out, idx

    def _map(self, idx, indent):
        out = {}
        while idx < len(self.lines) and self.lines[idx][0] == indent:
            entry = self.lines[idx]
            if entry[1].startswith("- "):
                break
            kv = _split_key(entry[1])
            if kv is None:
                raise ValueError("expected 'key: value' at line %d" % entry[2])
            key, rest = kv
            idx += 1
            if len(entry) > 3:
                out[key] = _block_scalar(rest, entry[3])
            elif rest:
                out[key] = _scalar(rest)
            elif idx < len(self.lines) and self.lines[idx][0] > indent:
                out[key], idx = self._block(idx, self.lines[idx][0])
            elif idx < len(self.lines) and self.lines[idx][0] == indent and \
                    self.lines[idx][1].startswith("-"):
                out[key], idx = self._list(idx, indent)
            else:
                out[key] = None
        return out, idx

def _strip_comment(s):
    quote = None
    for i, ch in enumerate(s):
        if quote:
            if ch == quote:
                quote = None
        elif ch in ("'", '"'):
            quote = ch
        elif ch == "#" and (i == 0 or s[i - 1] in " \t"):
            return s[:i].rstrip()
    return s

def _split_key(s):
    if s.startswith(("'", '"')):
        q = s[0]
        end = s.find(q, 1)
        if end == -1:
            return None
        key, after = s[1:end], s[end + 1:].lstrip()
        if not after.startswith(":"):
            return None
        return key, after[1:].strip()
    depth = 0
    for i, ch in enumerate(s):
        if ch in "[{":
            depth += 1
        elif ch in "]}":
            depth -= 1
        elif ch == ":" and depth == 0 and (i + 1 == len(s) or s[i + 1] in " \t"):
            return s[:i].strip(), s[i + 1:].strip()
    return None

def _block_scalar(indicator, raw_lines):
    lines = [l for l in raw_lines]
    nonblank = [l for l in lines if l.strip()]
    if not nonblank:
        return ""
    cut = min(len(l) - len(l.lstrip(" ")) for l in nonblank)
    body = [l[cut:] if l.strip() else "" for l in lines]
    while body and not body[-1]:
        body.pop()
    if indicator.startswith(">"):
        text = " ".join(x for x in body if x)
    else:
        text = "\n".join(body)
    return text if indicator.endswith("-") else text + "\n"

def _scalar(s):
    s = s.strip()
    if s.startswith("[") and s.endswith("]"):
        inner = s[1:-1].strip()
        return [_scalar(x) for x in _split_flow(inner)] if inner else []
    if s.startswith("{") and s.endswith("}"):
        inner = s[1:-1].strip()
        out = {}
        for part in _split_flow(inner) if inner else []:
            kv = _split_key(part)
            if kv is None:
                raise ValueError("bad flow map entry: %r" % part)
            out[kv[0]] = _scalar(kv[1]) if kv[1] else None
        return out
    if len(s) >= 2 and s[0] == s[-1] == '"':
        return json.loads(s)
    if len(s) >= 2 and s[0] == s[-1] == "'":
        return s[1:-1].replace("''", "'")
    low = s.lower()
    if low in ("true", "yes", "on"):
        return True if low == "true" else s
    if low == "false":
        return False
    if low in ("null", "~", ""):
        return None
    if re.match(r"^[-+]?\d+$", s):
        return int(s)
    if re.match(r"^[-+]?(\d+\.\d*|\.\d+|\d+)([eE][-+]?\d+)?$", s):
        return float(s)
    return s

def _split_flow(s):
    parts, depth, quote, cur = [], 0, None, ""
    for ch in s:
        if quote:
            cur += ch
            if ch == quote:
                quote = None
            continue
        if ch in ("'", '"'):
            quote = ch
        elif ch in "[{":
            depth += 1
        elif ch in "]}":
            depth -= 1
        elif ch == "," and depth == 0:
            parts.append(cur.strip())
            cur = ""
            continue
        cur += ch
    if cur.strip():
        parts.append(cur.strip())
    return parts

# ---------------------------------------------------------------- $ref handling

def resolve_pointer(doc, ref):
    if not ref.startswith("#/"):
        return None  # external refs are not followed
    node = doc
    for part in ref[2:].split("/"):
        part = part.replace("~1", "/").replace("~0", "~")
        if isinstance(node, dict) and part in node:
            node = node[part]
        else:
            return None
    return node

def deref(doc, node, seen=None):
    """Follow a single $ref chain (not recursive into children)."""
    seen = seen or set()
    while isinstance(node, dict) and "$ref" in node:
        ref = node["$ref"]
        if ref in seen:
            return {}
        seen.add(ref)
        target = resolve_pointer(doc, ref)
        if target is None:
            return node
        node = target
    return node

def ref_name(node):
    if isinstance(node, dict) and isinstance(node.get("$ref"), str):
        return node["$ref"].rsplit("/", 1)[-1]
    return None

def iter_operations(spec):
    """Yield (path, method, operation, path_item) with path-level params merged."""
    for path, item in (spec.get("paths") or {}).items():
        if not isinstance(item, dict):
            continue
        item = deref(spec, item)
        shared = item.get("parameters") or []
        for method in HTTP_METHODS:
            op = item.get(method)
            if not isinstance(op, dict):
                continue
            yield path, method, op, shared

def op_parameters(spec, op, shared):
    """Return resolved parameters, operation-level overriding path-level."""
    merged = {}
    for p in list(shared) + list(op.get("parameters") or []):
        p = deref(spec, p)
        if isinstance(p, dict) and "name" in p:
            merged[(p.get("in"), p["name"].lower() if p.get("in") == "header" else p["name"])] = p
    return list(merged.values())

def schema_properties(spec, schema, depth=0, seen=None):
    """Flatten object properties (follows $ref, allOf). Returns dict name -> schema."""
    seen = seen if seen is not None else set()
    out = {}
    if depth > 12 or not isinstance(schema, dict):
        return out
    name = ref_name(schema)
    if name:
        if name in seen:
            return out
        seen = seen | {name}
    schema = deref(spec, schema)
    for sub in schema.get("allOf") or []:
        out.update(schema_properties(spec, sub, depth + 1, seen))
    for k, v in (schema.get("properties") or {}).items():
        out[k] = v
    return out

def json_content(spec, content):
    """Pick the JSON-ish media type from a content map."""
    if not isinstance(content, dict):
        return None, None
    for mt, body in content.items():
        if "json" in mt:
            return mt, body
    for mt, body in content.items():
        return mt, body
    return None, None
```

## File: skills/coding/api-design-review/scripts/breaking_diff.py
size: 24345
sha: c94eec065f9a5a4b4f20c1e76734496fbca61787
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/scripts/breaking_diff.py

```text
#!/usr/bin/env python3
"""Diff two OpenAPI 3.x documents and classify every change.

Classes:
  BREAKING  an existing, correctly written client can fail or misbehave.
  RISKY     correct clients keep working, but clients that are strict
            (exhaustive enum switches, strict deserializers, status code
            checks) or generated SDKs may break. Decide case by case.
  SAFE      additive or loosening change that tolerant clients absorb.

The rules follow the request/response asymmetry: a request may get looser
and a response may get richer, never the reverse. See reference.md for the
reasoning and precedents (Google AIP-180, Stripe API upgrades, Zalando
compatibility rules, Microsoft/Azure breaking change policy).

Usage:
  python3 breaking_diff.py old.json new.yaml [--format text|md|json] [--no-fail]

Exit code 1 when there is at least one BREAKING change (use in CI), unless
--no-fail is given.
"""

import argparse
import json
import os
import re
import sys
from collections import OrderedDict

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _spec import load_spec, deref, ref_name, iter_operations, op_parameters, json_content  # noqa: E402

BREAKING, RISKY, SAFE = "BREAKING", "RISKY", "SAFE"
CONSTRAINT_UPPER = ("maxLength", "maximum", "maxItems", "maxProperties", "exclusiveMaximum")
CONSTRAINT_LOWER = ("minLength", "minimum", "minItems", "minProperties", "exclusiveMinimum")

def norm_path(path):
    return re.sub(r"\{[^}]+\}", "{}", path)

def stype(schema):
    t = schema.get("type")
    nullable = bool(schema.get("nullable"))
    if isinstance(t, list):
        nullable = nullable or "null" in t
        rest = [x for x in t if x != "null"]
        t = rest[0] if len(rest) == 1 else (",".join(sorted(rest)) or None)
    if t is None and "properties" in schema:
        t = "object"
    return t, nullable

class Differ:
    def __init__(self, old, new):
        self.old, self.new = old, new
        self.changes = []
        self.usage = OrderedDict()  # "schema Name (direction)" -> [where it is used]

    def add(self, cls, where, what, why=""):
        self.changes.append(OrderedDict(cls=cls, where=where, change=what, why=why))

    # ------------------------------------------------------------ schemas

    def schema(self, o, n, direction, where, seen=None, depth=0):
        """direction: 'request' (client sends) or 'response' (client reads)."""
        seen = seen or set()
        if depth > 25 or o is None or n is None:
            return
        key = (ref_name(o), ref_name(n))
        if key != (None, None):
            if key in seen:
                return
            seen = seen | {key}
        if key[0] and key[0] == key[1]:
            label = "schema %s (%s)" % (key[0], direction)
            first = label not in self.usage
            self.usage.setdefault(label, [])
            if where not in self.usage[label]:
                self.usage[label].append(where)
            if not first:
                return
            where = label
        o, n = deref(self.old, o), deref(self.new, n)
        if not isinstance(o, dict) or not isinstance(n, dict):
            return
        req = direction == "request"
        ot, onull = stype(o)
        nt, nnull = stype(n)

        if ot and nt and ot != nt:
            widening = (ot, nt) == ("integer", "number")
            if req and widening:
                self.add(SAFE, where, "type widened integer -> number")
            elif not req and (ot, nt) == ("number", "integer"):
                self.add(SAFE, where, "type narrowed number -> integer")
            else:
                self.add(BREAKING, where, "type changed %s -> %s" % (ot, nt),
                         "Clients serialize or parse this field with the old type.")
            return
        if o.get("format") != n.get("format") and (o.get("format") or n.get("format")):
            self.add(BREAKING if (o.get("format") and n.get("format")) or req else RISKY, where,
                     "format changed %s -> %s" % (o.get("format"), n.get("format")),
                     "Typed SDKs map formats to types (date-time to a datetime, int64 to a long).")
        if onull != nnull:
            if not req and nnull:
                self.add(BREAKING, where, "response field became nullable",
                         "Clients that dereference it without a null check will crash.")
            elif req and not nnull:
                self.add(BREAKING, where, "request field no longer accepts null")
            else:
                self.add(SAFE, where, "nullability loosened" if req else "response field no longer null")

        # enums
        oe, ne = o.get("enum"), n.get("enum")
        if oe is not None and ne is not None:
            added = [v for v in ne if v not in oe]
            removed = [v for v in oe if v not in ne]
            if added:
                if req:
                    self.add(SAFE, where, "enum values added: %s" % added)
                else:
                    self.add(RISKY, where, "enum values added to a response: %s" % added,
                             "Additive by most policies (Stripe, Google AIP-180), but clients "
                             "with exhaustive switches or strict enum types will fail. Say so in "
                             "the changelog and make sure SDKs have an 'unknown' fallback.")
            if removed:
                if req:
                    self.add(BREAKING, where, "enum values removed from a request: %s" % removed,
                             "Clients still send them and will now get errors.")
                else:
                    self.add(SAFE, where, "enum values no longer returned: %s" % removed)
        elif oe is None and ne is not None:
            self.add(BREAKING if req else SAFE, where, "enum restriction added")
        elif oe is not None and ne is None:
            self.add(SAFE if req else RISKY, where, "enum restriction removed")

        # numeric and length constraints
        for k in CONSTRAINT_UPPER + CONSTRAINT_LOWER + ("pattern",):
            ov, nv = o.get(k), n.get(k)
            if ov == nv or isinstance(ov, bool) or isinstance(nv, bool):
                continue
            if k == "pattern":
                tighter = nv is not None
            elif k in CONSTRAINT_UPPER:
                tighter = nv is not None and (ov is None or nv < ov)
            else:
                tighter = nv is not None and (ov is None or nv > ov)
            if req:
                self.add(BREAKING if tighter else SAFE, where,
                         "%s changed %s -> %s" % (k, ov, nv),
                         "Values that were valid before are now rejected." if tighter else "")
            else:
                self.add(SAFE if tighter else RISKY, where, "%s changed %s -> %s" % (k, ov, nv),
                         "" if tighter else "Clients may have sized buffers, columns or UI "
                         "for the old limit.")

        # objects
        op_, np_ = o.get("properties") or {}, n.get("properties") or {}
        oreq, nreq = set(o.get("required") or []), set(n.get("required") or [])
        removed = [k for k in op_ if k not in np_]
        added = [k for k in np_ if k not in op_]
        for k in removed:
            hint = self.rename_hint(op_[k], np_, added, k)
            if req:
                self.add(BREAKING, "%s.%s" % (where, k), "request field removed" + hint,
                         "Clients still send it. It will be rejected or, worse, silently "
                         "ignored.")
            else:
                self.add(BREAKING, "%s.%s" % (where, k), "response field removed" + hint,
                         "Clients that read it get nothing or crash.")
        for k in added:
            if req and k in nreq:
                self.add(BREAKING, "%s.%s" % (where, k), "new required request field",
                         "Every existing call is missing it.")
            else:
                self.add(SAFE, "%s.%s" % (where, k),
                         "new optional request field" if req else "new response field")
        for k in op_:
            if k not in np_:
                continue
            fw = "%s.%s" % (where, k)
            if req and k in nreq and k not in oreq:
                self.add(BREAKING, fw, "request field became required")
            elif req and k in oreq and k not in nreq:
                self.add(SAFE, fw, "request field became optional")
            elif not req and k in oreq and k not in nreq:
                self.add(BREAKING, fw, "response field no longer guaranteed (not required)",
                         "Clients assume it is always present.")
            self.schema(op_[k], np_[k], direction, fw, seen, depth + 1)

        oa, na = o.get("additionalProperties"), n.get("additionalProperties")
        if req and oa is not False and na is False:
            self.add(BREAKING, where, "request object now rejects unknown fields")
        if isinstance(o.get("items"), dict) and isinstance(n.get("items"), dict):
            self.schema(o["items"], n["items"], direction, where + "[]", seen, depth + 1)

        for comb in ("oneOf", "anyOf"):
            ov, nv = o.get(comb) or [], n.get(comb) or []
            if len(nv) > len(ov):
                self.add(SAFE if req else RISKY, where,
                         "%s gained %d variant(s)" % (comb, len(nv) - len(ov)),
                         "" if req else "Clients that switch on the variant may not handle it.")
            elif len(nv) < len(ov):
                self.add(BREAKING if req else SAFE, where,
                         "%s lost %d variant(s)" % (comb, len(ov) - len(nv)))
        for i, (a, b) in enumerate(zip(o.get("allOf") or [], n.get("allOf") or [])):
            self.schema(a, b, direction, where, seen, depth + 1)

    def rename_hint(self, old_prop, new_props, added, old_name=None):
        ot = stype(deref(self.old, old_prop))[0]
        same = [a for a in added if stype(deref(self.new, new_props[a]))[0] == ot]
        if len(same) != 1:
            same = [a for a in added if old_name and (a.startswith(old_name) or
                                                      old_name.startswith(a) or
                                                      a.replace("_", "").lower() ==
                                                      old_name.replace("_", "").lower())]
        if len(same) == 1:
            return " (looks renamed to '%s'; keep the old name as a deprecated alias)" % same[0]
        return ""

    # ------------------------------------------------------------ operations

    def ops(self, spec):
        out = OrderedDict()
        for path, method, op, shared in iter_operations(spec):
            out[(method, norm_path(path))] = (path, op, shared)
        return out

    def run(self):
        self.global_changes()
        old_ops, new_ops = self.ops(self.old), self.ops(self.new)
        for key, (path, op, shared) in old_ops.items():
            where = "%s %s" % (key[0].upper(), path)
            if key not in new_ops:
                self.add(BREAKING, where, "operation removed",
                         "Deprecate first, announce a sunset date, then remove in a new "
                         "major version.")
                continue
            npath, nop, nshared = new_ops[key]
            if npath != path:
                self.add(SAFE, where, "path parameter renamed: %s -> %s" % (path, npath),
                         "Wire format unchanged; generated SDK argument names may change.")
            self.operation(where, op, shared, nop, nshared)
        for key, (path, op, shared) in new_ops.items():
            if key not in old_ops:
                self.add(SAFE, "%s %s" % (key[0].upper(), path), "operation added")
        self.webhooks()
        return self.changes

    def global_changes(self):
        os_ = [s.get("url") for s in self.old.get("servers") or [] if isinstance(s, dict)]
        ns = [s.get("url") for s in self.new.get("servers") or [] if isinstance(s, dict)]
        for url in os_:
            if url not in ns:
                self.add(BREAKING, "servers", "server URL removed: %s" % url,
                         "Clients have the base URL hard-coded.")
        oschemes = (self.old.get("components") or {}).get("securitySchemes") or {}
        nschemes = (self.new.get("components") or {}).get("securitySchemes") or {}
        for name, s in oschemes.items():
            if name not in nschemes:
                self.add(BREAKING, "securitySchemes." + name, "security scheme removed")
            elif deref(self.old, s).get("type") != deref(self.new, nschemes[name]).get("type") or \
                    deref(self.old, s).get("in") != deref(self.new, nschemes[name]).get("in") or \
                    deref(self.old, s).get("name") != deref(self.new, nschemes[name]).get("name"):
                self.add(BREAKING, "securitySchemes." + name, "security scheme changed how "
                         "credentials are sent")
        ov, nv = str((self.old.get("info") or {}).get("version", "")), \
            str((self.new.get("info") or {}).get("version", ""))
        self.versions = (ov, nv)

    def operation(self, where, op, shared, nop, nshared):
        if op.get("operationId") and op.get("operationId") != nop.get("operationId"):
            self.add(BREAKING, where, "operationId changed %s -> %s" %
                     (op.get("operationId"), nop.get("operationId")),
                     "Wire format is unchanged, but generated SDK method names change.")
        if nop.get("deprecated") and not op.get("deprecated"):
            self.add(SAFE, where, "operation deprecated",
                     "Good: also send Deprecation and Sunset headers (RFC 9745, RFC 8594).")

        # security
        osec = op.get("security", self.old.get("security")) or []
        nsec = nop.get("security", self.new.get("security")) or []
        if self.sec_set(osec) != self.sec_set(nsec):
            if not osec or osec == [{}]:
                self.add(BREAKING, where, "authentication now required",
                         "Anonymous callers will get 401.")
            elif not nsec or nsec == [{}]:
                self.add(SAFE, where, "authentication no longer required")
            else:
                self.add(BREAKING, where, "security requirements changed: %s -> %s" %
                         (sorted(self.sec_set(osec)), sorted(self.sec_set(nsec))),
                         "Existing tokens may lack the new scheme or scope.")

        # parameters
        oparams = {(p.get("in"), p["name"]): p for p in op_parameters(self.old, op, shared)}
        nparams = {(p.get("in"), p["name"]): p for p in op_parameters(self.new, nop, nshared)}
        for k, p in oparams.items():
            pw = "%s %s param '%s'" % (where, k[0], k[1])
            if k not in nparams:
                if k[0] == "path":
                    continue  # covered by path rename
                moved = [nk for nk in nparams if nk[1] == k[1]]
                if moved:
                    self.add(BREAKING, pw, "parameter moved from %s to %s" % (k[0], moved[0][0]))
                else:
                    self.add(BREAKING if p.get("required") else RISKY, pw, "parameter removed",
                             "Clients still send it and it will be ignored or rejected. If it "
                             "changed behaviour (a filter, a flag), ignoring it silently is "
                             "worse than an error.")
                continue
            np_ = nparams[k]
            if np_.get("required") and not p.get("required"):
                self.add(BREAKING, pw, "parameter became required")
            elif p.get("required") and not np_.get("required"):
                self.add(SAFE, pw, "parameter became optional")
            self.schema(p.get("schema"), np_.get("schema"), "request", pw)
        for k, p in nparams.items():
            if k not in oparams and not any(ok[1] == k[1] for ok in oparams):
                pw = "%s %s param '%s'" % (where, k[0], k[1])
                if p.get("required") and k[0] != "path":
                    self.add(BREAKING, pw, "new required parameter", "Existing calls lack it.")
                elif k[0] != "path":
                    self.add(SAFE, pw, "new optional parameter")

        # request body
        ob = deref(self.old, op.get("requestBody")) or {}
        nb = deref(self.new, nop.get("requestBody")) or {}
        if nb and not ob:
            self.add(BREAKING if nb.get("required") else SAFE, where + " body",
                     "request body added" + (" and required" if nb.get("required") else ""))
        elif ob and not nb:
            self.add(BREAKING, where + " body", "request body removed")
        elif ob and nb:
            if nb.get("required") and not ob.get("required"):
                self.add(BREAKING, where + " body", "request body became required")
            self.content(ob.get("content") or {}, nb.get("content") or {}, "request",
                         where + " body")

        # responses
        oresp, nresp = op.get("responses") or {}, nop.get("responses") or {}
        oc = {str(c) for c in oresp}
        nc = {str(c) for c in nresp}
        osucc = {c for c in oc if c.startswith("2")}
        nsucc = {c for c in nc if c.startswith("2")}
        for c in sorted(osucc - nsucc):
            self.add(BREAKING, where, "success status %s no longer returned (now %s)" %
                     (c, ", ".join(sorted(nsucc)) or "none"),
                     "Clients that check the exact status code will treat success as failure.")
        for c in sorted(nsucc - osucc):
            if osucc and osucc <= nsucc:
                self.add(RISKY, where, "new success status %s" % c)
        for c in sorted((nc - oc) - nsucc):
            self.add(RISKY, where, "new error status %s documented" % c,
                     "Safe if this only documents existing behaviour. If the server now "
                     "fails in a new way, clients need to handle it.")
        for c in sorted((oc - nc) - osucc):
            self.add(SAFE, where, "error status %s no longer documented" % c)
        for c in sorted(oc & nc):
            ro = deref(self.old, oresp.get(c, oresp.get(int(c)) if c.isdigit() else None)) or {}
            rn = deref(self.new, nresp.get(c, nresp.get(int(c)) if c.isdigit() else None)) or {}
            rw = "%s -> %s" % (where, c)
            self.content(ro.get("content") or {}, rn.get("content") or {}, "response", rw)
            oh = {h.lower() for h in ro.get("headers") or {}}
            nh = {h.lower() for h in rn.get("headers") or {}}
            for h in sorted(oh - nh):
                self.add(BREAKING, rw, "response header '%s' removed" % h)
            for h in sorted(nh - oh):
                self.add(SAFE, rw, "response header '%s' added" % h)

    def sec_set(self, sec):
        out = set()
        for req in sec or []:
            for name, scopes in (req or {}).items():
                out.add((name, tuple(sorted(scopes or []))))
        return frozenset(out)

    def content(self, oc, nc, direction, where):
        for mt in oc:
            if mt not in nc:
                self.add(BREAKING, where, "media type '%s' removed" % mt)
        for mt in nc:
            if mt not in oc:
                self.add(SAFE, where, "media type '%s' added" % mt)
        for mt in oc:
            if mt in nc:
                self.schema((oc[mt] or {}).get("schema"), (nc[mt] or {}).get("schema"),
                            direction, where)

    def webhooks(self):
        oh, nh = self.old.get("webhooks") or {}, self.new.get("webhooks") or {}
        for name, item in oh.items():
            where = "webhook " + name
            if name not in nh:
                self.add(BREAKING, where, "webhook event removed")
                continue
            for method, op in (item or {}).items():
                nop = (nh[name] or {}).get(method)
                if not isinstance(op, dict) or not isinstance(nop, dict):
                    continue
                ob = deref(self.old, op.get("requestBody")) or {}
                nb = deref(self.new, nop.get("requestBody")) or {}
                # the receiver reads the payload, so it follows response rules
                self.content(ob.get("content") or {}, nb.get("content") or {}, "response", where)
        for name in nh:
            if name not in oh:
                self.add(RISKY, "webhook " + name, "new webhook event type",
                         "Receivers subscribed to all events must ignore unknown types; "
                         "only safe if your docs promised that.")

def semver_advice(changes, versions):
    has_b = any(c["cls"] == BREAKING for c in changes)
    has_new = any(c["cls"] in (SAFE, RISKY) for c in changes)
    need = "major" if has_b else ("minor" if has_new else "patch")
    ov, nv = versions
    note = "Changes need a %s version bump." % need
    try:
        om, nm = int(ov.split(".")[0]), int(nv.split(".")[0])
        if has_b and nm <= om:
            note += " info.version went %s -> %s, which does not signal a breaking change." % (ov, nv)
    except ValueError:
        pass
    return note

def render(changes, advice, fmt, a, b, usage):
    touched = OrderedDict()
    for label, wheres in usage.items():
        if any(c["where"].startswith(label) for c in changes):
            touched[label] = wheres
    if fmt == "json":
        return json.dumps({"old": a, "new": b, "advice": advice, "changes": changes,
                           "shared_schema_usage": touched}, indent=2)
    counts = {k: sum(1 for c in changes if c["cls"] == k) for k in (BREAKING, RISKY, SAFE)}
    lines = []
    head = "%d breaking, %d risky, %d safe. %s" % (counts[BREAKING], counts[RISKY], counts[SAFE], advice)
    if fmt == "md":
        lines.append("# API diff: %s -> %s\n\n%s\n" % (os.path.basename(a), os.path.basename(b), head))
        for cls in (BREAKING, RISKY, SAFE):
            items = [c for c in changes if c["cls"] == cls]
            if not items:
                continue
            lines.append("## %s (%d)\n" % (cls.title(), len(items)))
            for c in items:
                lines.append("- `%s`: %s%s" % (c["where"], c["change"],
                                               (". " + c["why"]) if c["why"] else ""))
            lines.append("")
        if touched:
            lines.append("## Where changed shared schemas are used\n")
            for label, wheres in touched.items():
                lines.append("- `%s`: %s" % (label, ", ".join("`%s`" % w for w in wheres)))
        return "\n".join(lines) + "\n"
    lines.append("API diff: %s -> %s" % (a, b))
    lines.append(head)
    for cls in (BREAKING, RISKY, SAFE):
        items = [c for c in changes if c["cls"] == cls]
        if not items:
            continue
        lines.append("")
        lines.append("%s (%d)" % (cls, len(items)))
        for c in items:
            lines.append("  %s: %s" % (c["where"], c["change"]))
            if c["why"]:
                lines.append("      " + c["why"])
    if touched:
        lines.append("")
        lines.append("Where changed shared schemas are used")
        for label, wheres in touched.items():
            lines.append("  %s: %s" % (label, "; ".join(wheres)))
    return "\n".join(lines) + "\n"

def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("old")
    ap.add_argument("new")
    ap.add_argument("--format", choices=("text", "md", "json"), default="text")
    ap.add_argument("--no-fail", action="store_true", help="always exit 0")
    args = ap.parse_args()
    old, new = load_spec(args.old), load_spec(args.new)
    d = Differ(old, new)
    changes = d.run()
    # de-duplicate (shared schemas are reached from several operations)
    seen, unique = set(), []
    for c in changes:
        k = (c["cls"], c["where"], c["change"])
        if k not in seen:
            seen.add(k)
            unique.append(c)
    advice = semver_advice(unique, d.versions)
    sys.stdout.write(render(unique, advice, args.format, args.old, args.new, d.usage))
    if not args.no_fail and any(c["cls"] == BREAKING for c in unique):
        sys.exit(1)

if __name__ == "__main__":
    main()
```

## File: skills/coding/api-design-review/scripts/lint_openapi.py
size: 38483
sha: b8a0acf35d3da823bfc3b4ec578965c9183f1fdf
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/scripts/lint_openapi.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/scripts/lint_openapi.py

## File: skills/coding/api-design-review/scripts/sdk_surface.py
size: 27307
sha: e4f88f23f7c307dda56873f1e32df5852b366151
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/scripts/sdk_surface.py

```text
#!/usr/bin/env python3
"""Dump the public surface of a Python package or a TypeScript .d.ts file as a
tree, with ergonomics hints, so a reviewer can judge the SDK as a whole.

Usage:
  python3 sdk_surface.py <python.module.name> [--path DIR] [--depth 2]
  python3 sdk_surface.py path/to/index.d.ts
  options: --format text|json   --no-hints   --private

Python: the module is imported (so its import side effects run; only point it
at code you trust). "Public" means __all__ when defined, otherwise names
without a leading underscore that are defined in the package itself.

TypeScript: a lightweight parser reads exported functions, classes,
interfaces, types, enums, consts and namespaces from a .d.ts file. It does
not type-check and does not follow imports.

Hints flag the patterns that most often hurt SDK users: boolean flag
arguments, long positional parameter lists, mutable defaults, missing
docstrings and type annotations, 'any' in TypeScript, optional parameters
before required ones, timeouts that default to "wait forever", and
exception classes with no common base.
"""

import argparse
import importlib
import inspect
import json
import os
import pkgutil
import re
import sys
import types
from collections import Counter, OrderedDict

# ====================================================================== Python

class PySurface:
    def __init__(self, root_name, depth, include_private, hints):
        self.root_name = root_name
        self.depth = depth
        self.private = include_private
        self.want_hints = hints
        self.hints = []
        self.stats = Counter()
        self.exceptions = []

    def hint(self, where, kind, msg):
        if self.want_hints:
            self.hints.append(OrderedDict(where=where, kind=kind, hint=msg))

    def public(self, name):
        return self.private or not name.startswith("_")

    def run(self):
        mod = importlib.import_module(self.root_name)
        tree = self.module(mod, 0)
        self.exception_hints()
        return tree

    def module(self, mod, level):
        self.stats["modules"] += 1
        node = OrderedDict(kind="module", name=mod.__name__, doc=_first_line(mod.__doc__),
                           members=[])
        names = getattr(mod, "__all__", None)
        explicit = names is not None
        if names is None:
            names = sorted(n for n in vars(mod) if self.public(n))
        for name in names:
            if not hasattr(mod, name):
                continue
            obj = getattr(mod, name)
            if isinstance(obj, types.ModuleType):
                continue
            home = getattr(obj, "__module__", None)
            if not explicit and home and not (home == mod.__name__ or
                                              home.startswith(self.root_name + ".") or
                                              home == self.root_name or
                                              home.lstrip("_") == mod.__name__.lstrip("_")):
                continue  # re-exported from elsewhere (typing, os, ...)
            where = "%s.%s" % (mod.__name__, name)
            if inspect.isclass(obj):
                cnode = self.cls(obj, where)
                if obj.__name__ != name:
                    cnode["name"] = "%s = %s" % (name, obj.__name__)
                node["members"].append(cnode)
            elif callable(obj):
                node["members"].append(self.func(obj, where, name))
            else:
                self.stats["constants"] += 1
                node["members"].append(OrderedDict(kind="const", name=name,
                                                   type=type(obj).__name__,
                                                   value=_short_repr(obj)))
        if hasattr(mod, "__path__") and level < self.depth:
            for info in sorted(pkgutil.iter_modules(mod.__path__), key=lambda i: i.name):
                if not self.public(info.name) or info.name in ("tests", "test"):
                    continue
                full = "%s.%s" % (mod.__name__, info.name)
                try:
                    sub = importlib.import_module(full)
                except Exception as exc:  # noqa: BLE001
                    node["members"].append(OrderedDict(kind="module", name=full,
                                                       error="import failed: %s" % exc))
                    continue
                node["members"].append(self.module(sub, level + 1))
        return node

    def cls(self, c, where):
        self.stats["classes"] += 1
        bases = [b.__name__ for b in c.__bases__ if b is not object]
        is_exc = issubclass(c, BaseException)
        if is_exc:
            self.exceptions.append(c)
            self.stats["exceptions"] += 1
        node = OrderedDict(kind="exception" if is_exc else "class", name=c.__name__,
                           bases=bases, doc=_first_line(c.__doc__), members=[])
        if not c.__doc__ or (c.__doc__ and c.__doc__ == (c.__bases__[0].__doc__ if c.__bases__ else None)):
            self.stats["undocumented"] += 1
            if not is_exc:
                self.hint(where, "no-docstring", "Public class has no docstring.")
        init = c.__dict__.get("__init__")
        if init is not None and callable(init):
            node["init"] = self.signature(init, where + ".__init__", "__init__", method=True)
        for name, raw in c.__dict__.items():
            if name.startswith("_") and not self.private:
                continue
            mwhere = "%s.%s" % (where, name)
            if isinstance(raw, property):
                node["members"].append(OrderedDict(kind="property", name=name,
                                                   readonly=raw.fset is None,
                                                   type=_ann(_ret_ann(raw.fget))))
            elif isinstance(raw, (staticmethod, classmethod)):
                f = raw.__func__
                m = self.func(f, mwhere, name, method=isinstance(raw, classmethod))
                m["kind"] = "staticmethod" if isinstance(raw, staticmethod) else "classmethod"
                node["members"].append(m)
            elif inspect.isfunction(raw) or inspect.ismethoddescriptor(raw) or \
                    inspect.isbuiltin(raw):
                node["members"].append(self.func(raw, mwhere, name, method=True))
            elif not callable(raw):
                node["members"].append(OrderedDict(kind="attr", name=name,
                                                   type=type(raw).__name__,
                                                   value=_short_repr(raw)))
        return node

    def func(self, f, where, name, method=False):
        self.stats["methods" if method else "functions"] += 1
        node = OrderedDict(kind="method" if method else "function", name=name,
                           async_=inspect.iscoroutinefunction(f),
                           doc=_first_line(getattr(f, "__doc__", None)))
        node.update(self.signature(f, where, name, method))
        if not getattr(f, "__doc__", None):
            self.stats["undocumented"] += 1
            self.hint(where, "no-docstring", "Public callable has no docstring.")
        if re.search(r"[a-z][A-Z]", name) and not name.startswith("_"):
            self.hint(where, "naming", "camelCase name in Python. PEP 8 uses snake_case "
                      "for functions and methods.")
        return node

    def signature(self, f, where, name, method=False):
        try:
            sig = inspect.signature(f)
        except (TypeError, ValueError):
            return OrderedDict(sig="(...)")
        params = list(sig.parameters.values())
        if method and params and params[0].name in ("self", "cls"):
            params = params[1:]
        positional = [p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
        annotated = sum(1 for p in params if p.annotation is not p.empty) + \
            (1 if sig.return_annotation is not sig.empty else 0)
        self.stats["params"] += len(params)
        self.stats["annotated"] += annotated
        self.stats["annotation_slots"] += len(params) + (0 if name == "__init__" else 1)
        if len(positional) > 4:
            self.hint(where, "long-positional",
                      "%d positional parameters (%s). Callers will pass them in the wrong order; "
                      "make the optional ones keyword-only with '*'." %
                      (len(positional), ", ".join(p.name for p in positional)))
        for p in positional:
            if isinstance(p.default, bool):
                self.hint(where, "bool-positional",
                          "'%s=%s' is a boolean flag that can be passed by position, so call "
                          "sites read as f(x, True). Make it keyword-only." % (p.name, p.default))
            if isinstance(p.default, (list, dict, set)):
                self.hint(where, "mutable-default",
                          "'%s' has a mutable default (%r), shared across calls." % (p.name, p.default))
        for p in params:
            if p.name in ("timeout", "timeout_s", "timeout_seconds", "read_timeout") \
                    and p.default is None:
                self.hint(where, "no-default-timeout",
                          "'%s' defaults to None, which usually means wait forever. A network "
                          "SDK should ship a finite default timeout." % p.name)
            elif p.name.startswith("timeout") and type(p.default) is object:
                self.hint(where, "no-default-timeout",
                          "'%s' defaults to a sentinel object, which usually means 'use the "
                          "global socket default', and that is no timeout unless the caller "
                          "set one. Calls can hang forever. Ship a finite default." % p.name)
        return OrderedDict(sig=_format_sig(sig, method))

    def exception_hints(self):
        if len(self.exceptions) < 2:
            return
        roots = set()
        for e in self.exceptions:
            mine = [b for b in e.__mro__[1:] if b in self.exceptions]
            if not mine:
                roots.add(e.__name__)
        if len(roots) > 1:
            self.hint(self.root_name, "exception-roots",
                      "Public exceptions have %d separate roots (%s). Users cannot catch "
                      "'every error from this library' with one except clause. Give them one "
                      "base class." % (len(roots), ", ".join(sorted(roots))))

def _first_line(doc):
    if not doc:
        return ""
    for line in doc.strip().splitlines():
        if line.strip():
            return line.strip()[:100]
    return ""

def _short_repr(v):
    r = repr(v)
    return r if len(r) <= 60 else r[:57] + "..."

def _ann(a):
    if a is None or a is inspect.Signature.empty:
        return ""
    if isinstance(a, type):
        return a.__name__
    return str(a).replace("typing.", "")

def _ret_ann(f):
    try:
        return inspect.signature(f).return_annotation
    except (TypeError, ValueError):
        return None

def _format_sig(sig, method):
    params = list(sig.parameters.values())
    if method and params and params[0].name in ("self", "cls"):
        params = params[1:]
    text = str(sig.replace(parameters=params))
    text = re.sub(r" at 0x[0-9a-fA-F]+>", ">", text)  # memory addresses change every run
    return text.replace("typing.", "")

def render_py(node, indent=0):
    pad = "  " * indent
    out = []
    k = node["kind"]
    if k == "module":
        out.append("%smodule %s%s" % (pad, node["name"],
                                      ("  # " + node["doc"]) if node.get("doc") else
                                      ("  # " + node["error"] if node.get("error") else "")))
        for m in node.get("members", []):
            out.extend(render_py(m, indent + 1))
    elif k in ("class", "exception"):
        bases = "(%s)" % ", ".join(node["bases"]) if node["bases"] else ""
        init = node.get("init", {}).get("sig", "")
        out.append("%s%s %s%s%s%s" % (pad, k, node["name"], bases, init,
                                      ("  # " + node["doc"]) if node.get("doc") else ""))
        for m in node["members"]:
            out.extend(render_py(m, indent + 1))
    elif k in ("function", "method", "staticmethod", "classmethod"):
        prefix = {"function": "def", "method": "def", "staticmethod": "@staticmethod def",
                  "classmethod": "@classmethod def"}[k]
        if node.get("async_"):
            prefix = "async " + prefix
        out.append("%s%s %s%s" % (pad, prefix, node["name"], node.get("sig", "(...)")))
    elif k == "property":
        out.append("%sproperty %s%s%s" % (pad, node["name"],
                                          (": " + node["type"]) if node["type"] else "",
                                          " (read-only)" if node["readonly"] else ""))
    elif k in ("const", "attr"):
        out.append("%s%s: %s = %s" % (pad, node["name"], node["type"], node["value"]))
    return out

# ================================================================== TypeScript

DECL_RE = re.compile(
    r"^(export\s+)?(declare\s+)?(default\s+)?(abstract\s+)?(async\s+)?"
    r"(function|class|interface|type|const|let|var|enum|namespace|module)\s+"
    r"([\w$.'\"]+)")

class TsSurface:
    def __init__(self, hints):
        self.want_hints = hints
        self.hints = []
        self.stats = Counter()

    def hint(self, where, kind, msg):
        if self.want_hints:
            self.hints.append(OrderedDict(where=where, kind=kind, hint=msg))

    def run(self, path):
        with open(path, "r", encoding="utf-8") as fh:
            src = fh.read()
        src = re.sub(r"/\*\*(.*?)\*/", lambda m: " @@JSDOC@@ ", src, flags=re.S)
        src = re.sub(r"/\*.*?\*/", " ", src, flags=re.S)
        src = re.sub(r"(?m)//.*$", "", src)
        tree = OrderedDict(kind="module", name=os.path.basename(path),
                           members=self.block(src, os.path.basename(path), top=True))
        errors = [m for m in tree["members"] if m["kind"] == "class" and m["name"].endswith("Error")]
        roots = [m["name"] for m in errors if not any(
            e["name"] in (m.get("heritage") or "") for e in errors if e is not m)]
        if len(roots) > 1:
            self.hint(tree["name"], "exception-roots",
                      "Error classes have %d separate roots (%s). Users cannot catch every SDK "
                      "error with one instanceof check. Give them one base class." %
                      (len(roots), ", ".join(roots)))
        return tree

    def statements(self, src):
        out, cur, depth, i = [], "", 0, 0
        n = len(src)
        while i < n:
            ch = src[i]
            if ch in "'\"`":
                end = i + 1
                while end < n and src[end] != ch:
                    end += 2 if src[end] == "\\" else 1
                cur += src[i:end + 1]
                i = end + 1
                continue
            cur += ch
            if ch in "{([":
                depth += 1
            elif ch in "})]":
                depth -= 1
                if depth == 0 and ch == "}":
                    head = cur.strip().replace("@@JSDOC@@", "").strip()
                    if not re.match(r"^(export\s+)?(declare\s+)?(type|const|let|var|default\s*\{|=)", head):
                        out.append(cur.strip())
                        cur = ""
            elif ch == ";" and depth == 0:
                out.append(cur.strip())
                cur = ""
            elif ch == "\n" and depth == 0 and re.search(r"[\w)\]>]\s*$", cur.strip() or "{") \
                    and re.match(r"\s*(export|declare|@@JSDOC@@|interface|class|function|type|"
                                 r"const|enum|namespace)\b", src[i + 1:i + 40]):
                out.append(cur.strip())
                cur = ""
            i += 1
        if cur.strip():
            out.append(cur.strip())
        return [s for s in out if s and s != ";"]

    def block(self, src, scope, top=False):
        members = []
        for stmt in self.statements(src):
            documented = stmt.lstrip().startswith("@@JSDOC@@")
            while stmt.lstrip().startswith("@@JSDOC@@"):
                stmt = stmt.lstrip()[len("@@JSDOC@@"):]
            stmt = stmt.strip().rstrip(";").strip()
            if not stmt:
                continue
            if re.match(r"^export\s*(\*|\{)", stmt):
                members.append(OrderedDict(kind="re-export", text=re.sub(r"\s+", " ", stmt)))
                continue
            m = DECL_RE.match(stmt)
            if not m:
                continue
            exported = bool(m.group(1)) or not top or stmt.startswith("declare")
            if not exported:
                continue
            kind, name = m.group(6), m.group(7).strip("'\"")
            where = "%s.%s" % (scope, name) if not top else name
            node = OrderedDict(kind=kind, name=name)
            if kind not in ("namespace", "module"):
                self.stats["declarations"] += 1
                if documented:
                    self.stats["documented"] += 1
                else:
                    self.hint(where, "no-docs", "Exported %s has no JSDoc comment." % kind)
            if kind == "function":
                sig = stmt[m.end():].strip()
                node["sig"] = _squash(sig)
                self.stats["functions"] += 1
                self.check_params(where, sig)
            elif kind in ("class", "interface"):
                head, body = _split_body(stmt[m.end():])
                node["heritage"] = _squash(head)
                node["members"] = self.members(body, where, kind)
                self.stats[kind + "es" if kind == "class" else kind + "s"] += 1
            elif kind in ("namespace", "module"):
                _, body = _split_body(stmt[m.end():])
                node["members"] = self.block(body, where)
            elif kind == "enum":
                _, body = _split_body(stmt[m.end():])
                node["values"] = [v.split("=")[0].strip() for v in body.split(",") if v.strip()]
            else:
                node["sig"] = _squash(stmt[m.end():])[:160]
                if kind == "type" and re.search(r"\bany\b", stmt):
                    self.hint(where, "any", "Type uses 'any', which turns off checking for users.")
            members.append(node)
        return members

    def members(self, body, where, kind):
        out = []
        carry = False
        for raw in _split_top(body, ";\n"):
            documented = "@@JSDOC@@" in raw or carry
            line = raw.replace("@@JSDOC@@", "").strip().rstrip(",;").strip()
            carry = documented and not line
            if not line or line.startswith(("private ", "#")) or re.match(r"^(static\s+)?private\b", line):
                continue
            mods = re.match(r"^((public|protected|readonly|static|abstract|declare|override|async)\s+)*", line)
            modtext = mods.group(0) if mods else ""
            rest = line[len(modtext):]
            mwhere = "%s.%s" % (where, re.split(r"[(:<?\s]", rest, 1)[0])
            mm = re.match(r"^(get\s+|set\s+)?(new\s*|[\w$]+|\[[^\]]+\])?(\??)\s*(<[^(]*>)?\s*\(", rest)
            if mm and (mm.group(2) or rest.startswith("(")):
                self.stats["methods"] += 1
                if not documented and kind == "class":
                    self.hint(mwhere, "no-docs", "Public method has no JSDoc comment.")
                out.append(OrderedDict(kind="method", text=_squash(modtext + rest)))
                self.check_params(mwhere, rest[rest.index("("):])
            else:
                self.stats["properties"] += 1
                out.append(OrderedDict(kind="property", text=_squash(modtext + rest)))
                if re.search(r":\s*any\b", rest):
                    self.hint(mwhere, "any", "Property typed 'any'.")
        return out

    def check_params(self, where, sig):
        if not sig.startswith("(") and "(" in sig:
            sig = sig[sig.index("("):]
        if not sig.startswith("("):
            return
        depth, end = 0, 0
        for i, ch in enumerate(sig):
            depth += ch in "({[<"
            depth -= ch in ")}]>" and not (ch == ">" and i and sig[i - 1] == "=")
            if depth == 0:
                end = i
                break
        params = [p.strip() for p in _split_top(sig[1:end], ",") if p.strip()]
        ret = sig[end + 1:].strip().lstrip(":").strip()
        if len(params) > 4:
            self.hint(where, "long-positional", "%d positional parameters. Group the optional "
                      "ones into an options object." % len(params))
        seen_optional = False
        for p in params:
            name = re.split(r"[?:=]", p, 1)[0].strip()
            optional = "?" in p.split(":")[0] or "=" in p
            if optional:
                seen_optional = True
            elif seen_optional and not p.startswith("..."):
                self.hint(where, "optional-before-required",
                          "Required parameter '%s' comes after an optional one." % name)
            if re.search(r":\s*boolean\s*$", p):
                self.hint(where, "bool-positional",
                          "'%s: boolean' is a positional flag, so call sites read as f(x, true). "
                          "Use an options object." % name)
            if re.search(r":\s*any\b", p):
                self.hint(where, "any", "Parameter '%s' is typed 'any'." % name)
            if re.match(r"timeout", name, re.I) is None and "callback" in name.lower():
                self.hint(where, "callback", "Callback parameter '%s'. Modern TS SDKs return "
                          "Promises." % name)
        if re.match(r"any\b", ret):
            self.hint(where, "any", "Returns 'any'.")

def _squash(s):
    return re.sub(r"\s+", " ", s).strip()

def _split_body(s):
    depth = 0
    for i, ch in enumerate(s):
        if ch in "(<[":
            depth += 1
        elif ch in ")>]" and not (ch == ">" and i and s[i - 1] == "="):
            depth -= 1
        elif ch == "{" and depth == 0:
            close = _match_brace(s, i)
            return s[:i], s[i + 1:close]
    return s, ""

def _match_brace(s, start):
    depth = 0
    for i in range(start, len(s)):
        if s[i] == "{":
            depth += 1
        elif s[i] == "}":
            depth -= 1
            if depth == 0:
                return i
    return len(s)

def _split_top(s, seps):
    out, cur, depth = [], "", 0
    for i, ch in enumerate(s):
        if ch in "({[<":
            depth += 1
        elif ch in ")}]>" and not (ch == ">" and i and s[i - 1] == "="):
            depth -= 1
        if ch in seps and depth == 0:
            out.append(cur)
            cur = ""
            continue
        cur += ch
    out.append(cur)
    return out

def render_ts(node, indent=0):
    pad = "  " * indent
    out = []
    k = node["kind"]
    if k == "module":
        out.append("%smodule %s" % (pad, node["name"]))
        for m in node["members"]:
            out.extend(render_ts(m, indent + 1))
    elif k in ("class", "interface"):
        out.append("%s%s %s%s" % (pad, k, node["name"],
                                  (" " + node["heritage"]) if node.get("heritage") else ""))
        for m in node["members"]:
            out.append("%s  %s %s" % (pad, "fn  " if m["kind"] == "method" else "prop", m["text"]))
    elif k in ("namespace", "module"):
        out.append("%snamespace %s" % (pad, node["name"]))
        for m in node["members"]:
            out.extend(render_ts(m, indent + 1))
    elif k == "enum":
        out.append("%senum %s { %s }" % (pad, node["name"], ", ".join(node["values"])))
    elif k == "re-export":
        out.append("%s%s" % (pad, node["text"]))
    else:
        out.append("%s%s %s %s" % (pad, k, node["name"], node.get("sig", "")))
    return out

# ======================================================================== main

def summary_lines(stats, kind):
    if kind == "py":
        slots = stats["annotation_slots"] or 1
        callables = stats["functions"] + stats["methods"] + stats["classes"]
        return ["%d modules, %d classes (%d exceptions), %d functions, %d methods, %d constants."
                % (stats["modules"], stats["classes"], stats["exceptions"], stats["functions"],
                   stats["methods"], stats["constants"]),
                "Docstrings on %d%% of public classes and callables. Type annotations on %d%% "
                "of parameter and return slots." %
                (100 - (100 * stats["undocumented"] // (callables or 1)),
                 100 * stats["annotated"] // slots)]
    total = stats["declarations"] or 1
    return ["%d exported declarations (%d functions, %d classes, %d interfaces), %d members "
            "(%d methods, %d properties)." %
            (stats["declarations"], stats["functions"], stats["classes"], stats["interfaces"],
             stats["methods"] + stats["properties"], stats["methods"], stats["properties"]),
            "JSDoc on %d%% of exported declarations." % (100 * stats["documented"] // total)]

def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("target", help="Python module name (e.g. 'json') or a .d.ts file")
    ap.add_argument("--path", help="directory to add to sys.path before importing")
    ap.add_argument("--depth", type=int, default=2, help="submodule depth for packages")
    ap.add_argument("--format", choices=("text", "json"), default="text")
    ap.add_argument("--no-hints", action="store_true")
    ap.add_argument("--private", action="store_true", help="include _private names")
    args = ap.parse_args()

    if args.target.endswith(".ts"):
        surf = TsSurface(not args.no_hints)
        tree = surf.run(args.target)
        lines = render_ts(tree)
        kind = "ts"
    else:
        if args.path:
            sys.path.insert(0, os.path.abspath(args.path))
        surf = PySurface(args.target, args.depth, args.private, not args.no_hints)
        tree = surf.run()
        lines = render_py(tree)
        kind = "py"

    if args.format == "json":
        print(json.dumps({"tree": tree, "stats": dict(surf.stats), "hints": surf.hints},
                         indent=2, default=str))
        return
    print("\n".join(lines))
    print("")
    print("Summary")
    for line in summary_lines(surf.stats, kind):
        print("  " + line)
    if surf.hints:
        by_kind = Counter(h["kind"] for h in surf.hints)
        print("")
        print("Hints (%s)" % ", ".join("%d %s" % (n, k) for k, n in by_kind.most_common()))
        quiet = ("no-docstring", "no-docs")
        for h in surf.hints:
            if h["kind"] not in quiet:
                print("  [%s] %s: %s" % (h["kind"], h["where"], h["hint"]))
        undocumented = [h["where"] for h in surf.hints if h["kind"] in quiet]
        if undocumented:
            print("  [docs] %d public names have no doc comment, for example: %s%s" % (
                len(undocumented), ", ".join(undocumented[:8]),
                " (use --format json for the full list)" if len(undocumented) > 8 else ""))

if __name__ == "__main__":
    main()
```

## File: skills/coding/api-design-review/examples/bookshop-v1.json
size: 10228
sha: fe581d09cc001fdcab5f88c9e6483dc6fb1b14ec
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/examples/bookshop-v1.json

```text
{
  "openapi": "3.1.0",
  "info": {
    "title": "Bookshop Orders API (deliberately flawed sample)",
    "version": "1.4.0",
    "description": "A fictional API with common design mistakes planted on purpose, used to test the api-design-review scripts."
  },
  "servers": [{ "url": "https://api.bookshop.example/v1" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/getCustomers": {
      "get": {
        "operationId": "getCustomers",
        "summary": "List customers",
        "responses": {
          "200": {
            "description": "All customers",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } }
          }
        }
      }
    },
    "/customer/{customerId}": {
      "parameters": [{ "name": "customerId", "in": "path", "required": true, "schema": { "type": "integer" } }],
      "get": {
        "operationId": "getCustomer",
        "responses": {
          "200": { "description": "A customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "put": {
        "operationId": "updateCustomer",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } },
        "responses": {
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } },
          "400": { "description": "Bad input" }
        }
      }
    },
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/OrderStatus" } },
          { "name": "customerId", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "Every order",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "operationId": "createOrder",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewOrder" } } }
        },
        "responses": {
          "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } },
          "400": { "description": "Invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Slow down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/orders/{order_id}": {
      "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "operationId": "getOrder",
        "responses": {
          "200": { "description": "An order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "patch": {
        "operationId": "updateOrder",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["shippingAddress", "notes"],
                "properties": {
                  "shippingAddress": { "type": "string", "maxLength": 500 },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }
        }
      },
      "delete": {
        "operationId": "getOrder",
        "responses": { "204": { "description": "Deleted" } }
      }
    },
    "/orders/{order_id}/items": {
      "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "operationId": "listOrderItems",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } },
                    "has_more": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/orders/{order_id}/refund": {
      "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "post": {
        "operationId": "refundOrder",
        "requestBody": {
          "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "reason": { "type": "string" } } } } }
        },
        "responses": {
          "200": { "description": "Refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }
        }
      }
    },
    "/payments": {
      "post": {
        "operationId": "createPayment",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }
        },
        "responses": {
          "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } },
          "402": { "description": "Card declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/shippingLabels/{label_id}": {
      "get": {
        "operationId": "getShippingLabel",
        "parameters": [{ "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Label PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "security": [],
        "responses": { "200": { "description": "OK" } }
      }
    }
  },
  "webhooks": {
    "order.shipped": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": { "type": "string" },
                  "order": { "$ref": "#/components/schemas/Order" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Acknowledged" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "schemas": {
      "Customer": {
        "type": "object",
        "required": ["id", "email"],
        "properties": {
          "id": { "type": "integer" },
          "email": { "type": "string", "format": "email" },
          "full_name": { "type": "string" },
          "nickname": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "OrderStatus": {
        "type": "string",
        "enum": ["pending", "Shipped", "CANCELLED"]
      },
      "Order": {
        "type": "object",
        "required": ["id", "customer_id", "status", "total", "created_at"],
        "properties": {
          "id": { "type": "string" },
          "customer_id": { "type": "integer" },
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "total": { "type": "number", "format": "double" },
          "currency": { "type": "string" },
          "shippingAddress": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updatedDate": { "type": "string" },
          "shipped": { "type": "integer", "description": "Unix seconds" }
        }
      },
      "NewOrder": {
        "type": "object",
        "required": ["customer_id", "items"],
        "properties": {
          "customer_id": { "type": "integer" },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } },
          "notes": { "type": "string", "maxLength": 1000 }
        }
      },
      "OrderItem": {
        "type": "object",
        "properties": {
          "isbn": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 },
          "unitPrice": { "type": "number" }
        }
      },
      "Payment": {
        "type": "object",
        "required": ["order_id", "amount"],
        "properties": {
          "id": { "type": "string", "readOnly": true },
          "order_id": { "type": "string" },
          "amount": { "type": "number" },
          "card_token": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "message": { "type": "string" } }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": { "msg": { "type": "string" }, "status": { "type": "integer" } }
          }
        }
      }
    }
  }
}
```

## File: skills/coding/api-design-review/examples/bookshop-v2.yaml
size: 10205
sha: 5174c426f0143d9dbbd78bb4523228ddd7418d0e
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/examples/bookshop-v2.yaml

```text
# v2 of the deliberately flawed sample. Some changes fix v1 problems,
# some quietly break existing clients. breaking_diff.py should tell them apart.
openapi: 3.1.0
info:
  title: Bookshop Orders API (deliberately flawed sample)
  version: 1.5.0          # minor bump, although several changes below are breaking
  description: >
    Version two of the fictional sample API.
servers:
  - url: https://api.bookshop.example/v1
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      operationId: listCustomers
      parameters:
        - name: limit
          in: query
          schema: {type: integer, default: 20, maximum: 100}
        - name: starting_after
          in: query
          schema: {type: string}
      responses:
        '200':
          description: A page of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {$ref: '#/components/schemas/Customer'}
                  has_more: {type: boolean}
        default:
          $ref: '#/components/responses/Problem'
  /customer/{customerId}:
    parameters:
      - name: customerId
        in: path
        required: true
        schema: {type: string}
    get:
      operationId: getCustomer
      responses:
        '200':
          description: A customer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Customer'}
        '404':
          description: Not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
    put:
      operationId: updateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/Customer'}
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Customer'}
        '400':
          description: Bad input
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema: {$ref: '#/components/schemas/OrderStatus'}
        - name: limit
          in: query
          schema: {type: integer, default: 20, maximum: 100}
        - name: starting_after
          in: query
          schema: {type: string}
      responses:
        '200':
          description: A page of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {$ref: '#/components/schemas/Order'}
                  has_more: {type: boolean}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
    post:
      operationId: createOrder
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema: {type: string, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NewOrder'}
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Order'}
        '400':
          description: Invalid
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
        '429':
          description: Slow down
          headers:
            Retry-After:
              schema: {type: integer}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /orders/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    get:
      operationId: getOrder
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Order'}
        '404':
          description: Not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
    patch:
      operationId: updateOrder
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shippingAddress: {type: string, maxLength: 200}
                notes: {type: string}
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Order'}
    delete:
      operationId: deleteOrder
      deprecated: true
      responses:
        '204':
          description: Deleted
  /orders/{order_id}/items:
    parameters:
      - name: order_id
        in: path
        required: true
        schema: {type: string}
    get:
      operationId: listOrderItems
      parameters:
        - name: page
          in: query
          schema: {type: integer, default: 1}
        - name: per_page
          in: query
          schema: {type: integer, default: 20, maximum: 100}
      responses:
        '200':
          description: Items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {$ref: '#/components/schemas/OrderItem'}
                  has_more: {type: boolean}
        '404':
          description: Not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /orders/{order_id}/refund:
    parameters:
      - name: order_id
        in: path
        required: true
        schema: {type: string}
    post:
      operationId: refundOrder
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount: {type: integer}
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]
      responses:
        '200':
          description: Refunded
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Order'}
  /payments:
    post:
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/Payment'}
      responses:
        '201':
          description: Payment
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Payment'}
        '402':
          description: Card declined
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /shippingLabels/{label_id}:
    get:
      operationId: getShippingLabel
      parameters:
        - name: label_id
          in: path
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Label PDF
          content:
            application/pdf:
              schema: {type: string, format: binary}
  /health:
    get:
      operationId: health
      responses:
        '200':
          description: OK
webhooks:
  order.shipped:
    post:
      parameters:
        - name: Webhook-Signature
          in: header
          required: true
          schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id: {type: string}
                type: {type: string}
                created_at: {type: string, format: date-time}
                order: {$ref: '#/components/schemas/Order'}
      responses:
        '200':
          description: Acknowledged
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    Problem:
      description: Error
      content:
        application/problem+json:
          schema: {$ref: '#/components/schemas/Error'}
  schemas:
    Customer:
      type: object
      required: [id, email]
      properties:
        id: {type: string}
        email: {type: string, format: email}
        full_name: {type: string}
        created_at: {type: string, format: date-time}
    OrderStatus:
      type: string
      enum: [pending, Shipped, CANCELLED, refunded]
    Order:
      type: object
      required: [id, customer_id, status, created_at]
      properties:
        id: {type: string}
        customer_id: {type: string}
        status: {$ref: '#/components/schemas/OrderStatus'}
        total_amount: {type: integer, description: 'Minor units, for example 1999 for 19.99'}
        currency: {type: string}
        shippingAddress: {type: [string, 'null']}
        created_at: {type: string, format: date-time}
        updatedDate: {type: string}
        shipped: {type: integer, description: Unix seconds}
    NewOrder:
      type: object
      required: [customer_id, items, currency]
      properties:
        customer_id: {type: string}
        items:
          type: array
          items: {$ref: '#/components/schemas/OrderItem'}
        notes: {type: string, maxLength: 1000}
        currency: {type: string, pattern: '^[A-Z]{3}$'}
    OrderItem:
      type: object
      properties:
        isbn: {type: string}
        quantity: {type: integer, minimum: 1}
        unitPrice: {type: number}
    Payment:
      type: object
      required: [order_id, amount]
      properties:
        id: {type: string, readOnly: true}
        order_id: {type: string}
        amount: {type: number}
        card_token: {type: string}
    Error:
      type: object
      required: [type, title, status, code, request_id]
      properties:
        type: {type: string, format: uri}
        title: {type: string}
        status: {type: integer}
        detail: {type: string}
        code: {type: string}
        request_id: {type: string}
```

## File: skills/coding/api-design-review/examples/review.md
size: 17487
sha: ebd887748d1e5be17a215f6f847dbbcc43527d50
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/examples/review.md

````text
# API design review: Bookshop Orders API v1.4.0

This review covers `bookshop-v1.json`, the proposed `bookshop-v2.yaml`, and the TypeScript SDK surface in `sample-sdk.d.ts`. The Bookshop API is fictional and was written with planted mistakes to test this skill. The raw tool output is in `out/`, and this review was written from that output plus a manual read of the spec.

The API is assumed to be public, with paying customers on v1.

## Summary

The API is not ready for more public users, because two flaws can cost customers money and several others are breaking to fix. A retried `POST /payments` or `POST /orders/{order_id}/refund` can charge or refund twice, because neither accepts an idempotency key, and webhooks are unsigned, so anyone can fake an `order.shipped` event. The proposed v2 fixes some of these, but it also ships 24 breaking changes under a minor version number (1.4.0 to 1.5.0), so every existing integration would break without warning.

The top fixes are listed below:

1. Add `Idempotency-Key` to every POST that creates something or moves money, and sign webhooks.
2. Ship v2's breaking changes as a new major version with a migration guide, or make them additive (keep old fields as deprecated aliases).
3. Settle one error schema, one ID type (string), one money format (integer minor units plus currency) and one list envelope with cursor pagination, before more clients depend on the current shapes.

## Scorecard

| Area | Score | Reason |
|---|---|---|
| Naming and consistency | 1 | snake_case fields with seven camelCase exceptions, a verb path (`/getCustomers`), a singular collection (`/customer/{customerId}`) and camelCase path segments |
| Resource modelling | 2 | Orders, items and payments are clear resources, but refund is an action that returns the Order instead of a Refund resource |
| Errors | 0 | Two error shapes, neither has a machine code or request id, and six operations document no errors at all |
| Evolution and versioning | 1 | URL version `/v1` exists, but v2 shows no compatibility rules, and the version number does not signal breaking changes |
| Pagination, filtering, sorting | 0 | Two of three list endpoints return everything as a bare array, and the third uses page numbers |
| Reliability | 0 | No idempotency anywhere, and the one 429 has no Retry-After |
| Long-running operations | n/a | None in this API |
| Webhooks | 0 | Unsigned, no event id, no event type field, no creation time |
| Auth ergonomics | 2 | Bearer tokens in the Authorization header, with `/health` correctly public, but 401 and 403 are documented on only one operation |
| Data formats | 0 | IDs are integers and strings, timestamps come in three formats, and money is a float in four places |
| SDK ergonomics | 1 | Promise-based with a raw `request` escape hatch, but long positional arguments, boolean flags, a callback method, `any` types and two unrelated error roots |
| CLI conventions | n/a | No CLI |

## Findings

### P0: Payments and refunds can run twice

**Where:** `POST /payments`, `POST /orders/{order_id}/refund` (also `POST /orders`, as P1).

If the response to `POST /payments` is lost (timeout, dropped connection, deploy), the client cannot tell whether the payment happened. A retry may charge the customer a second time, and not retrying may lose the order. Stripe solves this with an `Idempotency-Key` header, which the IETF is standardising in the draft "The Idempotency-Key HTTP Header Field". Google uses a `request_id` field (AIP-155) and Azure uses `Repeatability-Request-ID`.

Before:
```
POST /payments
{"order_id": "ord_1", "amount": 19.99}
```
After:
```
POST /payments
Idempotency-Key: 3f8c6b1e-9a2d-4a57-8c51-0b6f8d9e2a11
{"order_id": "ord_1", "amount": 1999, "currency": "EUR"}
```
The server stores the key with the first response for at least 24 hours and returns that stored response on a retry. If the same key arrives with a different body, the server returns 422. The SDK generates a key per call and reuses it across its own retries. Adding an optional header is not breaking.

### P0: Webhooks are unsigned

**Where:** `webhooks.order.shipped`.

Any server on the internet can POST a fake `order.shipped` event to a receiver's endpoint, and a receiver that ships goods or sends emails on that event will act on it. The payload also has no event `id` to drop duplicates, no `type`, and no creation time to order events by.

After:
```
POST <receiver URL>
webhook-id: evt_2Lk9
webhook-timestamp: 1762611780
webhook-signature: v1,<base64 HMAC-SHA256 of "evt_2Lk9.1762611780.<raw body>">

{"id": "evt_2Lk9", "type": "order.shipped", "created_at": "2026-11-08T14:03:00Z",
 "data": {"order_id": "ord_1"}}
```
This follows the Standard Webhooks spec. Stripe's `Stripe-Signature` header works the same way. Tell receivers to reject timestamps older than five minutes, to drop duplicate ids, and to fetch the order rather than trust a possibly stale copy in the event, because delivery order is not guaranteed. Changing the payload is breaking for current receivers, so send the new shape as a new event version and run both during a migration window.

### P1: List endpoints return everything, as a bare array

**Where:** `GET /orders`, `GET /getCustomers`.

Both endpoints return every record in one JSON array. Response time and memory grow with the data until the calls time out, and a top-level array cannot gain a `has_more` or cursor field later without breaking every client. The guidelines agree on this point. Stripe, Google (AIP-158), Microsoft and Zalando all wrap lists in an object, and Zalando prefers cursors over offsets.

Before:
```
GET /orders  ->  [ {...}, {...}, ... ]
```
After:
```
GET /orders?limit=50&starting_after=ord_8Fk2
->  {"data": [...], "has_more": true, "next_cursor": "ord_9Lm3"}
```
Document the default page size (e.g. 20) and the maximum (100). `GET /orders/{order_id}/items` already has the right envelope, but it uses `page`, which skips or repeats items when the list changes between pages. An order's items rarely change, so page numbers are acceptable there (P3).

### P1: Errors have no machine-readable code and two shapes

**Where:** schema `Error` (`{message}`, 5 responses) and schema `ErrorResponse` (`{error: {msg, status}}`, 2 responses), plus six operations with no documented error at all (`DELETE /orders/{order_id}`, `GET /getCustomers`, `GET /health`, `GET /shippingLabels/{label_id}`, `PATCH /orders/{order_id}`, `POST /orders/{order_id}/refund`).

Clients that need to react to an error (e.g. a declined card on `POST /payments`, versus out of stock on `POST /orders`) can only match on message text. After that, nobody can reword a message without breaking someone. Two shapes also mean two error handlers in every client.

After (RFC 9457 problem details, used for every 4xx and 5xx):
```
HTTP/1.1 402 Payment Required
Content-Type: application/problem+json
Request-Id: req_7Hq2LmX

{"type": "https://docs.bookshop.example/errors/card-declined",
 "title": "Card declined", "status": 402,
 "detail": "The card was declined by the issuer. Ask the customer for another card.",
 "code": "card_declined", "request_id": "req_7Hq2LmX"}
```
Migration: add `code`, `type` and `request_id` to both existing shapes now, which is additive. Keep `message` populated in `Error` (and `error.msg` in `ErrorResponse`) as deprecated fields until the next major version. The proposed v2 drops `message` outright, which the diff flags as breaking.

### P1: IDs are integers in some places and strings in others

**Where:** `Customer.id`, `Order.customer_id`, `NewOrder.customer_id` and the `{customerId}` path parameter are integers. `Order.id`, `Payment.id` and `Payment.order_id` are strings.

Clients have to remember which kind each ID is. Customer IDs above 2^53 will be corrupted by JavaScript clients, and sequential customer IDs reveal how many customers the shop has. Use opaque strings everywhere, ideally prefixed (`cus_`, `ord_`) as Stripe does, so a support engineer can tell an order ID from a customer ID.

Changing a type is breaking. Do it in the next major version, or add `customer_ref` as a string now and deprecate the integer field.

### P1: Money is a floating point number

**Where:** `Order.total` (double), `OrderItem.unitPrice`, `Payment.amount`, and the refund `amount` (float). `OrderItem.unitPrice`, `Payment.amount` and the refund `amount` have no currency.

Floats cannot represent 0.10 exactly, so clients in different languages round differently, and totals stop matching line items. An amount with no currency is ambiguous once a second currency exists.

After:
```json
{"total_amount": 1999, "currency": "EUR"}
```
This uses integer minor units like Stripe. Zalando's money object and Google's Money type are decimal alternatives. Add the new fields alongside the old ones, and deprecate the float fields.

### P1: Duplicate operationId breaks generated SDKs

**Where:** `GET /orders/{order_id}` and `DELETE /orders/{order_id}` are both `getOrder`.

Code generators either fail or silently produce one method that hides the other. Rename the DELETE to `deleteOrder`. Renaming an operationId changes generated method names, so it counts as breaking for SDK users (the diff reports it). The SDK should ship it in a major release, or keep `getOrder` as a deprecated alias in the handwritten SDK.

### P2: Naming is inconsistent

**Where:**
- Paths. `/getCustomers` has a verb, `/customer/{customerId}` is singular, and `/shippingLabels` and `/getCustomers` are camelCase while every other path is lowercase.
- Fields. Seven names are camelCase in a snake_case API, which are `Order.shippingAddress`, `Order.updatedDate`, `OrderItem.unitPrice`, the PATCH body's `shippingAddress`, and the `customerId` path and query parameters.
- Enum. `OrderStatus` mixes `pending`, `Shipped` and `CANCELLED`.

After:
```
GET /getCustomers          ->  GET /customers
GET /customer/{customerId} ->  GET /customers/{customer_id}
GET /shippingLabels/{id}   ->  GET /shipping-labels/{label_id}
shippingAddress            ->  shipping_address
OrderStatus: pending | shipped | cancelled
```
Add the new paths and names, keep the old ones as deprecated aliases with `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594), and remove them in the next major version.

### P2: Timestamps use three formats

**Where:** `created_at` is an RFC 3339 string, `Order.updatedDate` is a string with no format, and `Order.shipped` is Unix seconds.

Use RFC 3339 UTC strings everywhere with `format: date-time`, and one suffix (`_at`). After the change, the fields are `updated_at` and `shipped_at`.

### P2: PATCH requires fields, and customers only have PUT

**Where:** `PATCH /orders/{order_id}` requires `shippingAddress` and `notes`. `PUT /customer/{customerId}` has no PATCH alternative.

A client that only wants to change the notes must resend the address. With PUT, a client built before a new customer field existed will wipe that field on every update. Make every PATCH field optional (JSON Merge Patch, RFC 7396) and add `PATCH /customers/{customer_id}`. The v2 draft already makes the PATCH fields optional, which is a safe change.

### P2: Status codes and error docs are incomplete

- `POST /orders` and `POST /payments` return 200 for a create. Return 201 with a `Location` header in the next major version, because changing it now is breaking (the diff flags v2 for exactly this).
- The 429 on `POST /orders` has no `Retry-After`, so clients guess how long to wait. Add `Retry-After`, and document 429 on every operation.
- Eleven operations need auth but do not document 401. Four operations that address one resource do not document 404.

### P2: SDK ergonomics (`sample-sdk.d.ts`)

`sdk_surface.py` reported the following:

- `new BookshopClient(apiKey, baseUrl?, timeout?, retries?, debug?)` takes five positional arguments, while a `ClientOptions` interface already exists and is unused. Use `new BookshopClient({ apiKey, timeout })`, and read the key from an environment variable by default.
- `orders.list(status?, expand: boolean)` puts a required parameter after an optional one and uses a boolean flag, so callers must write `list(undefined, true)`.
- `orders.create(customerId: number, items, notes?, sendEmail?, coupon?)` takes five positional arguments with a boolean flag. Use `create({ customerId, items, sendEmail })`.
- `orders.cancel(id, callback)` is the only callback method in a Promise-based SDK.
- `customers: any`, `updateOrder(id, data: any): Promise<any>` and `WebhookHandler = (event: any)` turn off type checking where users need it most.
- `ApiError extends Error` and `RateLimitError` have no common base, so `catch (e) { if (e instanceof ApiError) }` misses rate limits. Make `RateLimitError extends ApiError`, and add `code` and `requestId` to `ApiError`.
- `ClientOptions.timeout` has no default. Ship a finite default (e.g. 60 seconds) and automatic retries on 429 and 503.
- `orders.list()` returns `Promise<Order[]>`, which will hide pagination. Return an async iterator that fetches pages as needed.
- Only 3 of 10 exported declarations have doc comments.

## Breaking-change risk list (v1.4.0 to proposed v2)

`breaking_diff.py` found 24 breaking, 2 risky and 34 safe changes (full output in `out/diff-v1-v2.md`). The version moves from 1.4.0 to 1.5.0, which tells users nothing broke. Either ship v2 as `/v2` (2.0.0) with a migration guide and a sunset date for v1, or rework it so every change is additive.

| Change in v2 | Who breaks | Additive alternative |
|---|---|---|
| `GET /getCustomers` removed | Every client listing customers | Keep it, mark it deprecated with Deprecation and Sunset headers, and point to `GET /customers` |
| `GET /orders` returns an object instead of an array | Every client listing orders | Serve the envelope only on `/v2`, or behind a version header |
| `Customer.id`, `customer_id` and `{customerId}` change from integer to string | Typed clients, and anyone who stored IDs as integers | Add string `customer_ref`, deprecate the integer |
| `Order.total` removed (renamed `total_amount`, integer) | Anyone showing totals | Return both fields during the deprecation period |
| `Error.message` removed, `ErrorResponse` replaced on 400 and 402 | Every error handler | Keep `message` (and `error.msg`) alongside the new fields |
| `NewOrder.currency` newly required | Every `POST /orders` call | Make it optional, with a default of the account currency |
| `POST /orders` and `POST /payments` now return 201 | Clients that check `== 200` | Only in a major version |
| `Order.shippingAddress` becomes nullable | Clients that read it without a null check | Return an empty string, or only change it in v2 |
| `PATCH` `shippingAddress` maxLength drops from 500 to 200 | Clients with longer addresses get 400 | Keep 500 |
| Refund `amount` changes from number to integer, `reason` becomes an enum | Every refund call | Add `amount_minor` and accept free-text `reason` with a warning |
| `GET /health` now requires auth | Load balancers and uptime checks | Keep it public |
| `operationId` of DELETE renamed | Generated SDK users | Release with the SDK major version |
| Webhook payload drops `event` | Every receiver | Send a new event version and keep both during migration |
| `OrderStatus` gains `refunded` (risky) | Clients with exhaustive switches | Announce it, and document that clients must handle unknown values |
| `customerId` query filter removed from `GET /orders` (risky) | Clients filtering by customer now get all orders, silently | Keep the filter, or reject it with a 400 so the change is visible |

The second risky change is the most dangerous one in the list, because the request still succeeds. A client that filtered orders by customer now gets every customer's orders with no error.

The diff also confirms that v2 makes several safe improvements, which are cursor pagination on `/customers` and `/orders`, an optional `Idempotency-Key` on `POST /orders`, `Retry-After` on 429, signed webhooks with `id`, `type` and `created_at`, problem details fields on errors, optional PATCH fields, and a deprecation flag on `DELETE /orders/{order_id}`.

## What's good

- Auth uses a bearer token in the `Authorization` header, and `/health` is explicitly public with `security: []`.
- `Order.id`, `Payment.id` and the order path parameters are already opaque strings.
- `created_at` is an RFC 3339 `date-time` on both Customer and Order, which gives a clear standard to align the rest to.
- `GET /orders/{order_id}/items` already uses a `{data, has_more}` envelope with a documented maximum page size of 100, so it is the model for the other lists.
- `Order` carries `currency` next to `total`.
- `quantity` has `minimum: 1`, and `notes` has a `maxLength`, so validation rules are in the spec where SDK generators can use them.
- The SDK is Promise-based, exposes `readonly orders` as a resource namespace that mirrors the REST paths, and has a typed raw `request<T>()` escape hatch.
- The v2 draft fixes many of the right things. Its problem is how it ships them.

## Not checked

- Runtime behaviour, which includes real latency, actual rate limits, whether the server really ignores unknown fields, and default sort order of lists.
- Documentation prose and examples, which `dx-audit` covers as part of onboarding.
- Security beyond the API surface (authorization rules, tenant isolation).
- The `./pagination` module re-exported by the SDK, which was not provided.
````

## File: skills/coding/api-design-review/examples/sample-sdk.d.ts
size: 1927
sha: 3ec0b5d29d9f158fea0837a0c77b33870217b711
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/examples/sample-sdk.d.ts

```text
// Deliberately flawed TypeScript SDK surface for testing sdk_surface.py.
// It belongs to the fictional "Bookshop Orders" API in this folder.

/** Options for creating a client. */
export interface ClientOptions {
  apiKey: string;
  baseUrl?: string;
  /** Milliseconds. There is no default, so requests can hang forever. */
  timeout?: number;
  maxRetries?: number;
}

/** Entry point for the SDK. */
export declare class BookshopClient {
  constructor(apiKey: string, baseUrl?: string, timeout?: number, retries?: number, debug?: boolean);
  readonly orders: OrdersResource;
  customers: any;
  /** Raw request escape hatch. */
  request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
  private signRequest(payload: string): string;
}

export declare class OrdersResource {
  /** List orders. Returns every order in one call. */
  list(status?: string, expand: boolean): Promise<Order[]>;
  get(id: string): Promise<Order>;
  create(customerId: number, items: OrderItem[], notes?: string, sendEmail?: boolean, coupon?: string): Promise<Order>;
  cancel(id: string, callback: (err: Error | null, order?: Order) => void): void;
  updateOrder(id: string, data: any): Promise<any>;
}

export interface Order {
  id: string;
  customer_id: number;
  status: "pending" | "Shipped" | "CANCELLED";
  total: number;
  createdAt: string;
}

export interface OrderItem {
  isbn: string;
  quantity: number;
}

export type WebhookHandler = (event: any) => void;

export declare enum OrderStatus {
  Pending = "pending",
  Shipped = "Shipped",
  Cancelled = "CANCELLED"
}

/** Thrown for any non-2xx response. */
export declare class ApiError extends Error {
  status: number;
  message: string;
}

export declare class RateLimitError {
  retryAfter: number;
}

export declare function verifyWebhook(payload: string, header: string, secret: string, tolerance?: number): boolean;

export * from "./pagination";
```

## File: skills/coding/api-design-review/reference.md
size: 28600
sha: 22b9a7ff7bc249dbe9a45f92d5640d13d65084ea
upstream: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/reference.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/dotslashsimran/simcraft/blob/main/skills/coding/api-design-review/reference.md

## File: README.md
upstream: https://github.com/dotslashsimran/simcraft/blob/main/README.md

````text
<div align="center">

# simcraft

**Skills that teach Claude how to do hard things well.**

24 skills for Claude Code, built from real projects, with the parts tutorials skip.

[![MIT License](https://img.shields.io/badge/license-MIT-black?style=flat-square)](LICENSE)
[![Skills](https://img.shields.io/badge/skills-24-black?style=flat-square)](#skills)
[![Claude Code](https://img.shields.io/badge/for-Claude%20Code-d97757?style=flat-square)](https://claude.com/claude-code)
[![Stars](https://img.shields.io/github/stars/dotslashsimran/simcraft?style=flat-square&color=black)](https://github.com/dotslashsimran/simcraft/stargazers)

[Install](#install) · [Video](#-video) · [Engineering](#-engineering) · [Learning](#-learning) · [Design](#-design) · [Planning](#-planning)

</div>

<br>

Each skill is a folder with a `SKILL.md`: the method, the judgement calls, and real, tested scripts for one kind of work. Claude Code loads the right one when your request matches. You don't call them by name, you just ask.

What makes them different: every skill covers **what breaks, how to check the result, and how to tell good from good enough.**

<br>

## Install

```bash
git clone https://github.com/dotslashsimran/simcraft ~/simcraft
mkdir -p ~/.claude/skills
for s in ~/simcraft/skills/*/*/; do ln -s "${s%/}" ~/.claude/skills/; done
cd ~/simcraft && npm i
```

Then open Claude Code and ask for something, like *"make a perspective-illusion loop of a rainy night street"*.

<details>
<summary>More setup details</summary>

<br>

- Claude Code finds skills one folder deep, so the loop links each one into `~/.claude/skills`. The categories are only for browsing. To install a single skill, link just that folder.
- A few skills have a one-time setup script in their folder (for example `setup.sh` for Whisper in rough-cut). Each SKILL.md says so at the top.
- **Needs:** Python 3.9+, Node 18+ (for skills that drive a browser or render video), and ffmpeg on your PATH or set as `FFMPEG=/path/to/ffmpeg`.
- **API keys** (only image-gen uses them) are read from your environment or `~/.config/simcraft/keys.env`. They never go in the repo.

</details>

<br>

## Skills

### 🎬 Video

| Skill | What it does |
|:--|:--|
| [**perspective-illusion**](skills/video/perspective-illusion/SKILL.md) | Illustrated 3D loops in the Japanese perspective-illusion style: flat scenes that open into depth. |
| [**code-loop**](skills/video/code-loop/SKILL.md) | Any three.js scene or shader rendered as a seamless loop, checked for seams, freezes and blinks. |
| [**reverse-engineer-video**](skills/video/reverse-engineer-video/SKILL.md) | Hand it a viral clip, get a remake plan: every cut, camera move and beat. |
| [**scripted-screencast**](skills/video/scripted-screencast/SKILL.md) | Product demos written as a script and rendered frame-perfect. No retakes. |
| [**repo-timelapse**](skills/video/repo-timelapse/SKILL.md) | Your git history as a video of the project growing. |
| [**rough-cut**](skills/video/rough-cut/SKILL.md) | Raw talking footage to a tight first cut: pauses, ums and retakes removed. |
| [**clean-audio**](skills/video/clean-audio/SKILL.md) | Voice cleanup that measures first, then keeps every word clear. |
| [**vox-explainer**](skills/video/vox-explainer/SKILL.md) | Vox-style explainer graphics timed word by word to a voiceover. |

### 🧑‍💻 Engineering

| Skill | What it does |
|:--|:--|
| [**codebase-map**](skills/coding/codebase-map/SKILL.md) | Learn an unfamiliar repo fast by tracing one real request end to end. |
| [**bisect-anything**](skills/coding/bisect-anything/SKILL.md) | Find the exact commit behind any regression, then the exact lines. |
| [**flaky-test-killer**](skills/coding/flaky-test-killer/SKILL.md) | Fix why a test is flaky, never with retries, and prove the fix. |
| [**benchmark-honestly**](skills/coding/benchmark-honestly/SKILL.md) | Benchmarks that survive scrutiny, with confidence intervals. |
| [**api-design-review**](skills/coding/api-design-review/SKILL.md) | Review an API, SDK or CLI, and catch breaking changes. |
| [**security-threat-model**](skills/coding/security-threat-model/SKILL.md) | Threat-model your own app from its real code, LLM apps included. |
| [**dx-audit**](skills/coding/dx-audit/SKILL.md) | Try a developer tool like a brand-new user and time it to first success. |

### 🧠 Learning

| Skill | What it does |
|:--|:--|
| [**paper-to-runnable**](skills/learning/paper-to-runnable/SKILL.md) | A research paper turned into the smallest honest implementation of its idea. |
| [**system-design-from-scratch**](skills/learning/system-design-from-scratch/SKILL.md) | Build a tiny real system, load-test it, break it, write up the trade-offs. |
| [**from-scratch**](skills/learning/from-scratch/SKILL.md) | Learn anything by building the smallest version of it, one step at a time. |
| [**teach-back**](skills/learning/teach-back/SKILL.md) | You explain it, Claude finds the gaps, you get a one-page cheat sheet. |

### 🎨 Design

| Skill | What it does |
|:--|:--|
| [**image-gen**](skills/design/image-gen/SKILL.md) | Images with your own Gemini or OpenAI key, consistent across a set. |
| [**brand-kit**](skills/design/brand-kit/SKILL.md) | Learn a brand from its live site into a kit the other skills apply. |

### 🧭 Planning

| Skill | What it does |
|:--|:--|
| [**skill-router**](skills/planning/skill-router/SKILL.md) | Picks the right skill for a task, or a chain of two or three. |
| [**next-step**](skills/planning/next-step/SKILL.md) | A big messy goal turned into one clear next action at a time. |
| [**video-script**](skills/planning/video-script/SKILL.md) | Short video scripts that sound like you, built from your own ramble. |

<br>

## Chains that work well

`skill-router` builds these on its own when a task has stages.

| Start with | Then |
|:--|:--|
| A viral clip | reverse-engineer-video → code-loop or perspective-illusion |
| A research paper | paper-to-runnable → vox-explainer |
| A new SDK | dx-audit → scripted-screencast |
| "It got slower" | benchmark-honestly → bisect-anything |
| A new job | codebase-map → flaky-test-killer |
| Raw footage | rough-cut → clean-audio |

<br>

## Credits

image-gen was inspired by [adamd9/skill-image-gen](https://github.com/adamd9/skill-image-gen), and vox-explainer by Charlie Hills' vox-animation skill (both MIT). Everything here is written from scratch.

## License

[MIT](LICENSE) © Simran Sachdeva
````
