waffo-stripe-migrate

An AI coding skill for Codex, Claude Code, and Cursor that migrates merchants already using Stripe-Java onto the Waffo drop-in SDK com.waffo:waffo-java-stripe — then verifies the migration end to end.

Merchants keep their existing com.stripe.* business code. They switch client construction to WaffoStripe.client(...) and tag the subscription checkouts they want routed to Waffo with metadata.source=waffo. Everything else keeps passing through to Stripe unchanged.

Install

# Auto-detect: installs to Codex, Claude Code, and/or Cursor if detected
npx @waffo/waffo-stripe-migrate

# Or target explicitly
npx @waffo/waffo-stripe-migrate --codex
npx @waffo/waffo-stripe-migrate --agents
npx @waffo/waffo-stripe-migrate --claude
npx @waffo/waffo-stripe-migrate --cursor

Then trigger the skill by saying "migrate from Stripe" (or "迁移 Stripe").

Cursor post-install

After npx @waffo/waffo-stripe-migrate --cursor, add to your .cursorrules (or .cursor/rules/waffo-stripe-migrate.mdc):

When the user asks to migrate from Stripe to Waffo, read and follow the instructions in
.cursor/skills/waffo-stripe-migrate/SKILL.md.
Load reference files from .cursor/skills/waffo-stripe-migrate/references/ as directed by SKILL.md.

Manual (any AI coding assistant)

Copy SKILL.md, references/, and scripts/ into your project. Point your AI assistant to read SKILL.md when migrating from Stripe.

What it does

A guided, six-step migration flow:

1. Identify — detect the Java project, stripe-java version, and any existing adapter wiring
2. Scan & review — run the usage scanner, then manually reconcile Stripe calls, subscription item/schedule usage, and webhook dependencies against the capability matrix
3. Compatibility report — produce a READY / READY-WITH-CHANGES / BLOCKED scan report (never an acceptance conclusion)
4. Integrate — show the full diff, get approval, then wire the dependency, WaffoStripe.client(...), metadata.source=waffo, and the signed webhook response
5. Sandbox E2E — output the Integration Test Plan Gate, then run merchant-side end-to-end verification (Phase A–E) through the project's own HTTP endpoints
6. Report — only after passing the report hard gate, emit a FULL / CONDITIONAL acceptance report

Built-in safeguards

• Routing vs. pass-through vs. fallback vs. hard-unsupported are decided from the actual SDK behavior in references/capability-matrix.md, not guessed.
• A subscription ownership migration gate blocks a migration conclusion when candidate Waffo checkout creates coexist with SubscriptionItem.* / SubscriptionSchedule.* calls until each is attributed.
• Static scan results are inventory only — ROUTED_LIKELY must be proven by E2E before it becomes ROUTED.
• Webhooks must use handle(...) and return the exact responseBody with X-SIGNATURE and Content-Type: application/json.
• wsub_ subscriptions cancel/update through the project's Waffo-native endpoint — Stripe Subscription.cancel/update is hard-unsupported for them.
• Fulfillment must move off checkout.session.completed to customer.subscription.created / invoice.paid.

Credentials

The skill bundles no credentials. Sandbox E2E requires the integrator's own Waffo Sandbox account (WAFFO_MERCHANT_ID / WAFFO_API_KEY / WAFFO_PRIVATE_KEY / WAFFO_PUBLIC_KEY) and a Stripe test key (STRIPE_SECRET_KEY=sk_test_…), supplied via environment variables or local config and never committed.

Progressive disclosure

Only SKILL.md is loaded initially. Reference files and the scanner are loaded on demand, saving tokens.

waffo-stripe-migrate/
├── SKILL.md                              # Entrypoint: 6-step flow + verification/report requirements
├── references/
│   ├── capability-matrix.md              # Routed / pass-through / fallback / unsupported support surface
│   ├── stripe-usage-detection.md         # Scanner scope + manual reconciliation gaps
│   ├── integration-steps.md              # Dependency, client, metadata, signed webhook, native cancel
│   ├── report-template.md                # Compatibility scan + formal acceptance report templates
│   └── e2e-verification.md               # Merchant-side Sandbox E2E protocol (Phase A–E) + report hard gate
├── scripts/
│   ├── scan_stripe_usage.py              # Regex-based Stripe usage scanner
│   └── test_scan_stripe_usage.py         # Scanner unit tests
└── docs/
    └── INDEX.md                          # FAQ / troubleshooting

Requirements

• Codex, Claude Code, Cursor, or any AI coding assistant that can read markdown instructions
• Python 3 (for the usage scanner)
• A Java project using stripe-java >= 24.11.0
• A Waffo merchant account (for Sandbox testing)

Changelog

See CHANGELOG.md.

License

MIT