Api spec brainstorming
Skill superluminar-io/pinky-promise/skills/api-spec-brainstorming
ALWAYS invoke this alongside superpowers:brainstorming. Covers two cases: (1) the user is building a service/API — capture the public API surface as a versioned spec; (2) the user is building a client, tool, or CLI that calls external services — surface missing registry entries. Required even when the prompt includes tech choices (language, cloud, framework) or is purely a consumer project.From its SKILL.md
npx -y skills add superluminar-io/pinky-promise --skill api-spec-brainstormingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.9 KB, as published. Nobody here has run it
API Spec Brainstorming
Define the public API surface of a service in parallel with the superpowers brainstorming skill.
When invoked
- A new service is being brainstormed and has no published spec in the registry
- A major version bump is being planned and the new API is being designed from scratch
How to ask questions
- Use
AskUserQuestiononly for questions with a small, closed set of options (2–4 choices), such as "Which protocol?" or "Streaming or unary?". - Ask all open-ended questions — message shapes, field names, types, operation names — as plain text in your response. Do not force them into
AskUserQuestion.
What to do
0. Check for external service dependencies
Do this first, before anything else.
Scan the user's message for any mention of calling, integrating with, or managing an external service (GitHub, Stripe, Twilio, any third-party API or platform) that is not being built in this repo. For each one found, surface immediately:
"The design depends on
<external-service>but no public API entry exists in the registry. Run/api-spec-import <url>to register it before planning begins."
This applies regardless of whether API_REGISTRY_REPO is configured.
0b. Determine project type
- Producer — the user is building a service that exposes a public API. Continue to all steps below.
- Consumer — the user is building a client, tool, or CLI that only calls external services and exposes no public API itself. Stop here — the API surface questions below do not apply.
0c. Check registry configuration
Read .claude/settings.json and the project CLAUDE.md for API_REGISTRY_REPO. If not found in either:
"⚠️ pinky-promise:
API_REGISTRY_REPOis not configured. The draft spec will be written locally but cannot be published to a registry or validated by consumers until you set this up. Seedocs/registry-setup.md."
Do not block — continue with the brainstorm.
1. Identify the service name
Infer from the project directory name or any draft content in context. If ambiguous:
"What is the canonical name for this service? (kebab-case, e.g.
order-service)"
2. Identify public operations
Ask:
"What operations does [service-name] need to expose to other services? These are the request/response calls other services will make."
For each operation named:
- Ask for input parameters (names and types)
- Ask for the return value
- Ask: "Is this truly part of the public contract, or is it an internal implementation detail?"
- Ask: "When should a caller use this operation — and when should they prefer a different one?"
Use the answer to the last question as the description field. Write it from the caller's perspective. Drop anything the user identifies as internal.
3. Identify events
Ask:
"Does [service-name] emit any events that other services would react to? (fire-and-forget — no response expected)"
For each event:
- Ask for the payload structure
- Ask: "What triggers this event, and what should a consumer do when it receives it?"
Use the answer as the description field.
If none, proceed.
4. Identify subscriptions
Ask:
"Does [service-name] support any ongoing streams or subscriptions — where a caller receives repeated data over time?"
For each subscription:
- Ask for input (what the subscriber provides) and output (what they receive)
- Ask: "When should a caller subscribe to this rather than polling via an operation?"
Use the answer as the description field.
If none, proceed.
5. Extract shared types
Review all inputs, outputs, and payloads collected. Identify shapes that appear more than once or that are complex enough to name. Propose names for them (PascalCase).
State: "I'll define these as named types: [list]."
6. Ask about bindings
Use AskUserQuestion for all closed-set choices in this step.
Protocol — ask with checkboxes (multi-select, a service can expose multiple protocols simultaneously):
- HTTP JSON REST
- gRPC
- GraphQL
- Other
For each protocol selected:
- Ask for the protocol-specific mapping of operations (open-ended, plain text)
- gRPC: ask for the proto
packagename (e.g.audit) — required for/<package>.<service>/<rpc>paths - HTTP only: ask for optional path prefix (e.g.
/v1) and connection URL - gRPC: ask for host and port
Authentication — ask with radio buttons (single-select):
- None
- Bearer token
- API key
- Basic (username/password)
- OAuth2 (client credentials)
- OAuth2 (password flow)
For OAuth2: ask for tokenUrl and scopes (open-ended). For API key: ask for header/query and header name. Do not ask for credential values.
Version scope — ask with radio buttons (single-select):
- All versions (no
contractVersion) - This major only — ask which (e.g.
1.*,2.*) - Exact version (e.g.
1.5.0)
Set contractVersion accordingly.
7. Produce the draft contract and bindings
Contract — use this exact shape. pinkyPromiseVersion: 1 always first. Version 1.0.0 for first-time specs; guardian-recorded major for redesigns. No bindings in this file.
{
"pinkyPromiseVersion": 1,
"name": "kebab-case-service-name",
"version": "1.0.0",
"description": "optional",
"operations": [
{ "name": "camelCase", "kind": "operation", "description": "caller-perspective", "input": { "fieldName": { "type": "string" } }, "output": { "type": "TypeName" } }
],
"events": [
{ "name": "camelCase", "kind": "event", "description": "caller-perspective", "payload": { "type": "TypeName" } }
],
"subscriptions": [
{ "name": "camelCase", "kind": "subscription", "description": "caller-perspective", "input": { "fieldName": { "type": "string" } }, "output": { "type": "TypeName" } }
],
"types": {
"PascalCase": { "kind": "object", "fields": { "id": { "type": "string" }, "optional": { "optional": true, "type": "number" } } },
"MyEnum": { "kind": "enum", "values": ["a", "b"] },
"MyUnion": { "kind": "union", "variants": [{ "type": "string" }, { "type": "number" }] }
}
}
Inline type expressions: { "type": "string|number|boolean|null|TypeName" }, { "type": "array", "items": { "type": "string" } }, { "optional": true, "type": "string" }. object, enum, union must be named types — never inline.
Bindings — use this exact shape. pinkyPromiseVersion: 1 always first.
{
"pinkyPromiseVersion": 1,
"service": "kebab-case-service-name",
"bindings": [
{
"contractVersion": "1.*",
"protocol": "http-json-rest",
"prefix": "/v1",
"operations": { "operationName": { "method": "GET", "path": "/resource/{id}" } },
"events": { "eventName": { "method": "POST", "path": "/webhooks/event" } },
"subscriptions": { "subName": { "path": "/resource/{id}/watch" } },
"connection": {
"url": "https://api.example.com",
"auth": { "type": "oauth2", "flow": "client_credentials", "tokenUrl": "https://auth.example.com/token", "scopes": ["api:read"] }
}
},
{
"contractVersion": "1.*",
"protocol": "grpc",
"package": "proto_package",
"service": "ProtoServiceName",
"operations": { "operationName": { "rpc": "RpcName" } },
"subscriptions": { "subName": { "rpc": "RpcName" } },
"connection": { "host": "service.internal", "port": 443 }
}
]
}
Auth types: bearer (consumer provides token), basic (username/password), api_key (add "in": "header", "name": "X-Key", consumer provides key), oauth2 with client_credentials or password flow. Omit auth if none required.
State both explicitly:
"Draft contract for [service-name]:
{ ... }Draft bindings:
{ ... }Both will be published when api-spec-publish is invoked."
Persist both to disk so they survive across sessions:
mkdir -p .pinky-promise
grep -qxF '.pinky-promise/registry/' .gitignore 2>/dev/null || echo '.pinky-promise/registry/' >> .gitignore
grep -qxF '.pinky-promise/credentials.json' .gitignore 2>/dev/null || echo '.pinky-promise/credentials.json' >> .gitignore
cat > .pinky-promise/draft-spec.json << 'SPEC'
<full contract JSON>
SPEC
cat > .pinky-promise/bindings.json << 'BINDINGS'
<full bindings JSON>
BINDINGS
Announce: "Draft contract and bindings written to .pinky-promise/. They will be published when the branch is finished."
Use AskUserQuestion (multi-select) to offer follow-up tooling. Options depend on the project role determined in step 0b:
Producer (service):
- Generate mock client — invoke
api-mock-server --clientto create a test harness that calls your server - Generate Pact contract tests — invoke
api-pact-generatefor provider verification setup - Nothing yet
Consumer (client/tool):
- Generate mock server — invoke
api-mock-server --serverto create a Prism/gRPC stub to test against - Generate Pact contract tests — invoke
api-pact-generatefor consumer interaction file - Nothing yet
Both roles:
- Generate mock client — for testing the server side
- Generate mock server — for testing the client side
- Generate Pact contract tests — for both producer and consumer
- Nothing yet
Invoke the selected skills in sequence.
Validation rules to enforce
- No inline
enum,union, orobject— define them in thetypesmap - All type references in
input/output/payloadare either inline type expressions or names defined intypes - Member names are camelCase
- Type names are PascalCase
- Service name is kebab-case