playbooks

home / skills / phrazzld / claude-config / stripe-scaffold

stripe-scaffold skill

/skills/stripe-scaffold

This skill generates working Stripe integration code from a design document, scaffolding backend, webhooks, and subscription UX for a production-ready app.

npx playbooks add skill phrazzld/claude-config --skill stripe-scaffold

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.4 KB
---
name: stripe-scaffold
description: |
  Generate Stripe integration code from a design document.
  Produces working code, not just templates.
effort: high
---

# Stripe Scaffold

Generate the code for a Stripe integration.

## Branching

Assumes you start on `master`/`main`. Before generating code:

```bash
git checkout -b feat/stripe-integration-$(date +%Y%m%d)
```

## Objective

Turn a design document into working code. Delegate implementation to Codex aggressively — that's what it's for.

## Process

**1. Review the Design**

Read the design document from `stripe-design`. Understand:
- Checkout flow
- Webhook events
- State management approach
- Access control logic

**2. Research Current Implementation**

Before generating code:
- Use Gemini to find current Stripe SDK usage patterns
- Check the Stripe docs for your specific use case
- Look at how similar apps implement this

Code patterns change. Don't rely on cached knowledge.

**3. Delegate to Codex**

For each component, delegate to Codex with clear specs:

```bash
codex exec --full-auto "Implement Stripe webhook handler for [events]. \
Follow pattern in [reference]. Use Convex mutations for state updates. \
Verify signature first. Handle idempotency. \
Run pnpm typecheck after." \
--output-last-message /tmp/codex-webhook.md 2>/dev/null
```

Then: `git diff --stat && pnpm typecheck && pnpm test`

**4. Components to Generate**

Typical Next.js + Convex stack:

**Backend:**
- `src/lib/stripe.ts` — Stripe client initialization
- `src/app/api/stripe/checkout/route.ts` — Checkout session creation
- `src/app/api/stripe/webhook/route.ts` — Webhook receiver (signature verification)
- `convex/stripe.ts` — Webhook event processing
- `convex/subscriptions.ts` — Subscription state management
- `convex/billing.ts` — Billing queries and portal session creation
- `convex/schema.ts` updates — Subscription fields on users
- `.env.example` updates — Document required variables

**Subscription Management UX (Required):**
Reference `stripe-subscription-ux` for full requirements.

- `components/billing/SubscriptionCard.tsx` — Current plan overview
- `components/billing/BillingCycleInfo.tsx` — Next billing date, amount
- `components/billing/PaymentMethodDisplay.tsx` — Card on file
- `components/billing/BillingHistory.tsx` — Past invoices
- `components/billing/ManageSubscriptionButton.tsx` — Opens Stripe Portal
- `components/billing/TrialBanner.tsx` — Trial status/countdown
- Settings page section for subscription management

**This UX is non-negotiable.** No Stripe integration is complete without it.

**5. Don't Forget**

- Trial handling: pass `trial_end` when user upgrades mid-trial
- Access control: check subscription status before gated features
- Error handling: webhook should return 200 even on processing errors (to prevent Stripe retries)
- Signature verification: MUST be first thing in webhook handler

## Quality Gates

After generation:
- `pnpm typecheck` — No type errors
- `pnpm lint` — No lint errors
- `pnpm test` — Tests pass (if they exist)
- Manual review of generated code

## Adaptation

Default stack is Next.js + Convex. If different:
- Express/Fastify: Different route setup, same Stripe logic
- Supabase/Postgres: Different ORM, same state management concepts
- No Convex: Webhook processing happens in the API route directly

The Stripe parts are the same; the framework parts adapt.

Overview

This skill generates a complete, working Stripe integration from a design document. It produces backend routes, Convex state handlers, and the required subscription management UI components so the integration is deployable, not just scaffolded. It assumes a Next.js + Convex stack by default but documents adaptation points for other stacks.

How this skill works

The skill reads a design document describing checkout flow, webhook events, state rules, and access control. It then creates Stripe client initialization, checkout and webhook API routes, Convex processing mutations/queries, environment variable examples, and a mandatory subscription UX. The process includes signature verification, idempotency handling, trial support, and post-generation quality gates (typecheck, lint, tests).

When to use it

  • You need a production-ready Stripe integration from a product spec.
  • You want end-to-end code (routes + DB state + UI) rather than templates.
  • You’re using Next.js + Convex or can adapt similar patterns to another stack.
  • You need webhook-driven subscription state with idempotency and signature verification.
  • You want a repeatable workflow that delegates detailed implementation to an AI coding assistant.

Best practices

  • Start a feature branch before generating code and keep changes scoped.
  • Verify Stripe signature first in the webhook handler and return 200 even on processing errors.
  • Include trial_end handling for upgrades during trials and enforce access control on gated routes.
  • Run pnpm typecheck, lint, and tests immediately after generation and manually review generated code.
  • Use environment examples (.env.example) and document required variables for deploys.

Example use cases

  • Implement checkout session creation and redirect flows for paid plans.
  • Process invoice.payment_succeeded, customer.subscription.* webhooks and update Convex state.
  • Show a subscription management section with billing history, card on file, and Manage Subscription button.
  • Create a portal session endpoint to let users manage billing via Stripe Portal.
  • Adapt webhook processing to Express/Fastify or Supabase/Postgres while preserving Stripe logic.

FAQ

Does this produce production-ready code?

Yes—code is intended to be working and deployable, but you must run typechecks, linting, and manual review before production.

Can I use this with frameworks other than Next.js + Convex?

Yes. The Stripe logic (checkout, webhook verification, idempotency, trial handling) is framework-agnostic; only route and DB wiring need adapting.

How are webhooks handled to avoid duplicate processing?

Webhook handlers verify signatures, implement idempotency checks, and update state via Convex mutations (or equivalent) so events are processed once.