How the API evolves without breaking the people who built on it — the versioning scheme, breaking-change discipline, and how deprecations are announced and retired.
Free & open · no signup · read-only — it ends by asking · nothing leaves your machine
You are working inside this repo. Mission: judge how this API changes over time — whether it can add and evolve without breaking existing integrations, and whether deprecations are announced, dated, and migratable rather than sprung on people.
Read-only pass. Read the API surface, its versioning, and its change history; change nothing but the report file.
Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.
a clear, consistent scheme (URL, header, or date) applied everywhere
a defined line for what counts as breaking, enforced not ad hoc
additive by default; old clients keep working
how a deprecation is announced, signaled (headers, docs), and dated
a real timeline and a migration path, not an indefinite "deprecated"
a changelog and notifications where consumers actually learn of changes
the fields and endpoints people depend on that were never meant to be public
One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.
Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.
Identify the versioning scheme, if any, and how consistently it is applied.
Versioning scheme — a clear, consistent scheme (URL, header, or date) applied everywhere.
Rank by how many integrations a change would break and how little warning they'd get.
Create VERSIONING.md at repo root.
Copy it and paste it into your agent inside the repo you want checked.
Install the goal plugin once — two commands — then just type /goal:api-versioning.
/plugin marketplace add GhostlyGawd/goal-prompts/plugin install goal@goal-promptsOr install only this Goal Prompt as /goal-api-versioning:
curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=113 shLet an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.
https://goal-prompts.vercel.app/raw/113.mdNothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.
# Goal: API Versioning & Deprecation You are working inside this repo. Mission: judge how this API changes over time — whether it can add and evolve without breaking existing integrations, and whether deprecations are announced, dated, and migratable rather than sprung on people. Read-only pass. Read the API surface, its versioning, and its change history; change nothing but the report file. ## Phase 1 — Learn how it changes - Identify the versioning scheme, if any, and how consistently it is applied. - Look at recent changes: which were additive and which broke callers. - Find how deprecations are currently signaled and communicated. ## Phase 2 — Audit through 7 lenses 1. **Versioning scheme** — a clear, consistent scheme (URL, header, or date) applied everywhere 2. **Breaking-change discipline** — a defined line for what counts as breaking, enforced not ad hoc 3. **Backward compatibility** — additive by default; old clients keep working 4. **Deprecation process** — how a deprecation is announced, signaled (headers, docs), and dated 5. **Sunset & migration** — a real timeline and a migration path, not an indefinite "deprecated" 6. **Change communication** — a changelog and notifications where consumers actually learn of changes 7. **Undocumented surface** — the fields and endpoints people depend on that were never meant to be public ## Phase 3 — Curate - Rank by how many integrations a change would break and how little warning they'd get. - For each gap, name the fix — a scheme, a compatibility rule, a deprecation header, a sunset policy. - Separate a one-time cleanup from the ongoing policy that prevents the next break. ## Phase 4 — Report Create `VERSIONING.md` at repo root: 1. **Current practice** — the versioning and deprecation reality today 2. **Breaking-change risks** — the changes or habits that will break callers, by exposure 3. **Policy** — the versioning scheme, compatibility rules, and deprecation timeline to adopt 4. **Signals** — the headers, changelog, and notices that keep consumers informed Start the report with today's date. If `VERSIONING.md` already exists from a previous run, read it first and lead with what changed since. ## Rules - Every consumer is code you cannot see; break it and you break trust silently - A deprecation without a date and a migration path is just a warning nobody acts on - No public API surface in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding. - If a `reports/` directory exists at the repo root, write the report there instead of the root. - Before asking, present the top findings as a ranked list in plain words - Report only — end by asking which versioning changes to make first
reports/ directory exists at the repo root, write the report there instead of the root.The webhooks this product sends and receives — delivery guarantees, retries, signing, and whether a consumer can actually build on them reliably.
The client libraries developers use to call this product — how fast they reach a first successful call, and how the SDK behaves when things go wrong.
The API's rate limits and quotas as a product surface — whether they protect the system while staying fair, predictable, and workable for real consumers.
The first hour a developer spends with this API — from landing on the docs to a working integration — and where they stall, guess, or give up.
Runs inside these playbooks — curated sequences you can launch with one paste: