Ends in commits Playbook · 6 briefs

Ship a Public API

Make an API developers actually want to build on.

See the sequence See real sample reports ↗

Free & open · no signup · audits are read-only — the Fixer asks before any edit · nothing leaves your machine

Why this sequence

Everything a developer meets when they build on you: webhooks, the SDK, versioning, rate limits, and the first-hour docs — then the Fixer ships the fixes as commits.

The map

Run it in order

The conductor fetches each brief in turn and writes its report before moving on — later briefs can build on earlier findings. Or copy any single stage to run it alone.

111Webhook Design AuditWEBHOOKS.mdAPI

112SDK Ergonomics AuditSDK.mdAPI

113API Versioning & DeprecationVERSIONING.mdAPI

114Rate-Limit & Quota DesignQUOTAS.mdAPI

115Developer Portal & OnboardingDEVPORTAL.mdAPI

47The FixerFIXLOG.mdAct

what you'll have at the end

6 reports in reports/, plus the run's own INDEX.md: WEBHOOKS.md, SDK.md, VERSIONING.md, QUOTAS.md, DEVPORTAL.md, FIXLOG.md. Feed them to the optional Studio to turn findings into commits, or run 28 · Roadmap Synthesis to merge them into one plan.

Get started

One paste runs the whole thing

Copy the conductor into your agent inside the repo you want checked. It runs each Goal Prompt in sequence, honoring each one's ask-first rule.

View raw ↗

In this playbook

The 6 briefs

111 · API

Webhook Design Audit

The webhooks this product sends and receives — delivery guarantees, retries, signing, and whether a consumer can actually build on them reliably.

112 · API

SDK Ergonomics Audit

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.

113 · API

API Versioning & Deprecation

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.

114 · API

Rate-Limit & Quota Design

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.

115 · API

Developer Portal & Onboarding

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.

47 · Act

The Fixer

Turns your root reports into commits. Asks the scope — all, high-priority, or its pick — then builds them in dependency order, one verified commit each.

# Playbook: Ship a Public API (conductor)

You are working inside this repo. Mission: execute the **Ship a Public API** playbook — 6 audit briefs in sequence, each producing one report file in the repo's `reports/` directory.

Everything a developer meets when they build on you: webhooks, the SDK, versioning, rate limits, and the first-hour docs — then the Fixer ships the fixes as commits.

## Before stage 1
- If `CHARTER.md` exists at the repo root or in `reports/`, read it first — its goals, non-goals, and invariants bound every recommendation in every stage. No charter? Proceed, and suggest 149 · The Charter afterwards.
- If there is no `reports/` directory at the repo root, create it now — every brief writes its report there once the directory exists, so the whole run lands in one folder instead of scattering generic filenames across the root.
- Before fetching stage 1, tell the operator in plain words what this playbook will do — one line per stage — and ask for the go-ahead.
- In a git repo, plan to commit as you go — one commit per report plus a final one for the index; make committing part of the go-ahead question, and skip it only if the operator says no.

## How to run each stage, in order
1. Fetch the brief with a read-only web request (for example: curl -s <url>).
2. If your harness can run subagents or fresh sessions, run each stage in one — a stage needs only the earlier report files at the repo root and in `reports/`, never this conversation.
3. Execute it exactly as written. Every brief is read-only toward the codebase; its only write is its own report file.
4. Confirm the report file exists (at the repo root or in `reports/`) before moving on, and stamp one provenance line under its title — `<playbook> · stage <N>/<M> · brief <id>` — so the file itself names the run that wrote it.
5. If committing, commit the report now, message `reports: <FILE> — <stage title> (<playbook> <N>/<M>)` — that per-stage trail is what lets any later session recover the whole run with one git log --grep.
6. After each stage, tell the operator in two or three plain sentences what it found — the single biggest finding and why it matters for this repo — and what comes next; never advance in silence.
7. Proceed to the next stage. Do not parallelize — later briefs may draw on earlier reports.

## Stages
1. **111 · Webhook Design Audit** — fetch https://goal-prompts.vercel.app/raw/111.md → writes `WEBHOOKS.md`
2. **112 · SDK Ergonomics Audit** — fetch https://goal-prompts.vercel.app/raw/112.md → writes `SDK.md`
3. **113 · API Versioning & Deprecation** — fetch https://goal-prompts.vercel.app/raw/113.md → writes `VERSIONING.md`
4. **114 · Rate-Limit & Quota Design** — fetch https://goal-prompts.vercel.app/raw/114.md → writes `QUOTAS.md`
5. **115 · Developer Portal & Onboarding** — fetch https://goal-prompts.vercel.app/raw/115.md → writes `DEVPORTAL.md`
6. **47 · The Fixer** — fetch https://goal-prompts.vercel.app/raw/47.md → writes `FIXLOG.md`

## After the final stage
- Write the run's index — `INDEX.md`, in the same directory as the reports (commit it last, if committing): the run date, the playbook name, each stage with its brief URL, and one line per report — file name, finding count (mark a null report as such), and its top two or three next steps. A session with no memory of this run must be able to start from that one file.
- Present the strongest findings across every report as one ranked list, in plain words — each with why it matters for this repo; the operator should not need to open a report file to act.
- Then ask which findings to fix. Unless 47 · The Fixer already ran as a stage of this playbook, offer to fetch https://goal-prompts.vercel.app/raw/47.md and implement exactly the operator's picks — one verified commit per finding. The report files stay on disk as the paper trail.
- Prefer a merged plan instead? Fetch https://goal-prompts.vercel.app/raw/28.md (Roadmap Synthesis) to fold the reports at the repo root and in `reports/` into one sequenced plan.
- Close with the handoff: if the run sits on an unmerged branch, offer to open a pull request titled `reports: <playbook> run <date> (<M> stages)` whose body is the index — the PR list is the first place a later session or teammate looks; either way, print a paste-ready handoff block naming the branch, the report directory, the file list, and `INDEX.md` as the place to start.

## Rules
- If a fetch fails, retry once; if it still fails, use the locally installed /goal:<slug> (or /goal-<slug>) command or the goal-prompts MCP get_brief tool for that stage; if neither exists, say so and stop — never improvise a brief from memory.
- Honor each brief's own rules, including ending by asking before any changes.
- If a stage's report already exists (at the repo root or in `reports/`), ask whether to re-run or skip that stage.
- A conductor caps at 16 stages — for a longer campaign, split it into two conductors and run them back-to-back.