/contribute-spec-fix

name: contribute-spec-fix
description: Fix a broken OpenAPI spec in jentic-public-apis with an OpenAPI Overlay, validate it (spectral lint + idempotency check), and contribute it back via a PR to the community catalog. Falls back to applying the same overlay to the local Jentic registry if the user can't wait for maintainer approval, and closes the loop by reacting when the upstream spec later changes (adopt update, or resolve an upstream-vs-overlay conflict). Use when an API spec is wrong/incomplete (bad server URL, missing enum, wrong content-type, missing param, etc.) and the fix should reach the community project, not just the local box.
metadata:
  kind: freeform
  argument-hint: "[vendor/api or path to the broken spec]"

Contribute a Spec Fix (Overlay → PR → optional local apply)

Fix a spec in `jentic-public-apis` the right way: capture the fix as an **OpenAPI Overlay**, validate it, and **open a PR so the whole community gets the fix**. This is the improvement flywheel — fixes made by AI agents are contributed back, not siloed on one machine.

Target: `$ARGUMENTS` (a `vendor/api` id like `posthog.com/posthog-api`, or a path to a spec).

If the vendor is **not in the catalog at all**, this is the wrong skill — use `import-new-api` instead; this skill only fixes specs that already exist.

The flywheel — read this first

        broken spec found
                │
                ▼
     write overlay  ──►  validate (lint + idempotency)  ──►  apply to openapi.json
                │
                ▼
     ┌─────────────────────────────────────────────┐
     │  DEFAULT: PR to jentic/jentic-public-apis     │  ← community gets the fix
     └─────────────────────────────────────────────┘
                │
                ▼  (only if the user is blocked on maintainer approval time)
     ┌─────────────────────────────────────────────┐
     │  FALLBACK: apply the SAME overlay to the      │  ← unblocks the user now;
     │  local Jentic registry — PR stays open        │    PR is still the source of truth
     └─────────────────────────────────────────────┘
                │
                ▼  (later: the registry keeps watching upstream)
     ┌─────────────────────────────────────────────┐
     │  upstream spec changes  ──►  registry emits:  │
     │   • update_available      → re-import to adopt│  ← fix merged upstream? adopt + retire
     │   • update_conflicts_overlay → operator picks │  ← never silently overwrites the fix
     └─────────────────────────────────────────────┘

**Always open the PR.** The local apply is an impatience valve, not a substitute — it uses the *same overlay document*, so nothing forks. Never skip the PR just because a local apply worked.

Prerequisites

• A local checkout of `jentic-public-apis`. Find it (don't assume the path):

`find ~ -maxdepth 4 -type d -name jentic-public-apis 2>/dev/null`. The repo has `origin` pointing at `jentic/jentic-public-apis`.

• `python3` — the format-preserving overlay applier (step 4) and the validation checks are Python.
• `spectral` on PATH (`spectral --version`) — used **only for linting** (step 6). Spectral is a

linter/validator; it has no command to apply an overlay and emit a modified spec.

• `npx` available — `bump-cli` (fetched on demand via `npx --yes bump-cli`) is used **only as the

idempotency cross-check** (step 5), never as the writer: it re-serializes and reorders keys, so it would reformat the whole file. Redocly 2.x can apply overlays too but only via a `redocly.yaml` config and it also reorders — same problem. No CLI applier preserves source formatting, which is why step 4 uses a small in-repo Python applier instead.

• `gh` authenticated (`gh auth status`) for the PR.
• For the local fallback only: a running Jentic control plane (default `http://127.0.0.1:8000`)

and a registered agent (`jentic doctor` shows a resolvable identity with a valid token).

Steps

1. Locate the spec and understand the fix

Resolve `$ARGUMENTS` to a spec at `apis/openapi/<vendor>/<api>/<version>/openapi.json` in the jentic-public-apis checkout. Read the relevant section and confirm with the user exactly what's wrong and what the fixed value should be (e.g. "servers only has the US host; add an EU host"). Note the `<vendor>`, `<api>`, and `<version>` **folder** path segments — you need them for the PR (they define where the overlay file lives).

> **Folder path ≠ registry identity.** The `jentic-public-apis` folder segments are *not* the > identity the registry serves under. On import the registry **slugifies** identity from the > spec's own `info` block: `vendor` from `x-vendor`/`contact.name` and `name` from `info.title`, > each lowercased with non-`[a-z0-9-]` → `-` (so `posthog.com` → `posthog-com`). Do **not** reuse > the folder segments in `/apis/...` URLs — they will 404. For the local-apply steps (9–10) get > the registry identity from the registry itself after import (shown there) and use *that* for > `$V/$N/$VER`.

2. Branch off the latest main

Never work on a dirty tree or a stale base (see the no-direct-push-to-main rule).

git -C <repo> fetch origin main
git -C <repo> switch -c fix/<vendor>-<short-slug> origin/main

If the working tree has an unrelated in-progress state that blocks the checkout, prefer an isolated `git worktree add -b fix/... <path> origin/main` so you don't disturb it. If you must clear it in place, record the current branch tip first and confirm with the user.

Confirm the branch is at the tip of origin/main: `git -C <repo> log --oneline -1`.

3. Write the overlay

Create `apis/openapi/<vendor>/<api>/<version>/meta/overlay.json` (JSON for JSON specs). Use the **OpenAPI Overlay 1.0.0** format. Prefer **remove-then-set** action pairs — they are deterministic regardless of the starting state, which is what makes the overlay idempotent:

{
  "overlay": "1.0.0",
  "info": { "title": "Overlay for the <Vendor> API", "version": "1.0.0" },
  "action