pinky-promise

pinky-promise

API contract enforcement for Claude Code. Keeps producer and consumer services in sync by hooking into every stage of the superpowers development workflow — brainstorming, planning, implementation, review, and branch completion.

When you build a service that other services call, you make a promise about its interface. pinky-promise makes that promise explicit, versioned, and enforced:

• Producers define their public API surface during brainstorming and publish it to a shared registry when the branch is complete.
• Consumers pin to a specific version and get their implementation validated against the published spec at every code review.
• Breaking changes are caught before they're planned, not after they're deployed.

pinky-promise is also flexible about where specs come from. Use /api-spec-import to register any external API — Stripe, Twilio, an internal platform service — directly from its OpenAPI, gRPC, or GraphQL spec. Once imported, consumer code calling that API gets the same contract validation as internally-owned services.

Everything lives in a git registry you control. No external services required.

What's coming

• API spec brainstorming
• Breaking change detection
• Consumer contract checks
• External API import (OpenAPI, gRPC, GraphQL)
• Spec publish to registry
• Mock server generation
• Pact consumer test generation
• MCP server generation
• Improved auth handling
• Consumer dependency drift detection
• Registry health check
• Monorepo layout support
• Async messaging and schema registry

See ROADMAP.md for details.

See it in action

Catching a breaking change before it's planned:

Requirements

• Claude Code with the superpowers plugin installed
• A git repository to use as the API registry (see Registry setup)
• SSH access to the registry from the machines running Claude Code

Installation

pinky-promise is not listed in the official Anthropic marketplace. Install it via the superluminar-io marketplace.

First, install superpowers if you haven't already:

/plugin install superpowers@claude-plugins-official

Add the pinky-promise marketplace (once per machine):

claude plugin marketplace add https://github.com/superluminar-io/pinky-promise

Then install (run from your project directory):

claude plugin install pinky-promise@superluminar-io --scope project

To update after new releases:

claude plugin marketplace update superluminar-io
claude plugin update pinky-promise@superluminar-io --scope project

From a local checkout (for development or contributing):

git clone [email protected]:superluminar-io/pinky-promise.git
./pinky-promise/install-local.sh /path/to/your/project

To sync changes after editing the plugin source:

./pinky-promise/install-local.sh /path/to/your/project --update

Getting started

First: set up the registry

The registry is a plain git repository shared across all your services. Create it once per organisation.

mkdir api-registry && cd api-registry
git init
mkdir -p services && touch services/.gitkeep
git add services/ && git commit -m "chore: init registry"
git remote add origin [email protected]:yourorg/api-registry.git
git push -u origin main

As a service producer

1. Install pinky-promise in your service repo (see Installation)

2. Configure the registry URL in .claude/settings.json:

{
  "env": {
    "API_REGISTRY_REPO": "[email protected]:yourorg/api-registry.git"
  }
}

3. Start a brainstorm — open a Claude Code session and describe what you're building. pinky-promise interleaves API surface questions with the design discussion and writes the draft to .pinky-promise/.

4. Finish the branch — pinky-promise publishes the spec to the registry automatically when the branch is completed.

As a service consumer

You only need access to the registry — not to the producer's codebase.

1. Install pinky-promise in your consumer repo (see Installation)

2. Configure the same registry URL in .claude/settings.json:

{
  "env": {
    "API_REGISTRY_REPO": "[email protected]:yourorg/api-registry.git"
  }
}

3. Start implementing — when your code calls another service, pinky-promise prompts you to declare the dependency in api-dependencies.json and validates every call against the published spec at planning, implementation, and code review.

Consuming an external API

If you're calling a third-party API (Stripe, Twilio, etc.) run /api-spec-import with its spec URL:

/api-spec-import https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json