| name | provider-track-selection |
| description | Choose the commerce provider (Stripe / Square / Shopify) and the tier (static hosted-checkout vs framework embedded-SDK) for a site, then point at the right template set. Use at the START of any commerce integration, before scaffolding. Routes on how the merchant's inventory truth already lives and the site's runtime. |
Provider & Tier Selection
The first decision in any web-commerce integration. Pick one provider per site and one tier, record the choice, then scaffold. Read ../../knowledge/provider-tracks-2026.md for the full capability matrix.
Step 1 — pick the provider (by where inventory truth lives)
| The merchant's situation | Provider | Why |
|---|
| Storefront with an in-store POS; online inventory must mirror it | Square | Native single catalog/inventory ledger — POS stays the source of truth; clean reconciliation |
| Payments-first; catalog owned in the site/DB; no POS | Stripe | Payments-only, app owns the catalog — least assumption |
| Wants a hosted store + checkout and is fine with Shopify owning it | Shopify | Owns catalog + checkout; you integrate, you don't rebuild |
Tie-breakers: an existing in-store POS almost always decides it (match the POS ecosystem so in-store and online unify). If the merchant already runs Square in-store → Square. Already on Shopify → Shopify.
Step 2 — pick the tier (by the site's runtime)
| Site runtime | Tier | What gets scaffolded |
|---|
| Static HTML (no SSR/framework) | static | Hosted/redirect checkout + a thin serverless function (Cloudflare Worker / Vercel/Netlify Function) + KV for the webhook receiver and idempotency store |
| Next.js / Astro / a JS framework | framework | Embedded SDK checkout + server routes + webhooks |
A "static" site still needs the serverless function — a browser cannot verify a webhook or hold idempotency state safely. Never fake webhook verification client-side (see webhook-hardening).
Step 3 — record the choice
Write a commerce.manifest.json into the target repo: { provider, tier, posReconciliation, generatedAt, templateVersion }. A later invocation reads it instead of re-interviewing.
Step 4 — scaffold
Copy templates/shared/ + templates/<provider>/<tier>/ into the site, then run the commerce-gold-standard-rubric checks. Every payment/PII diff is then reviewed by ravenclaude-core/security-reviewer (mandatory).
Do NOT
- Try to make one site support all three providers behind a unified adapter (the leaky-adapter trap — see the CLAUDE.md doctrine).
- Scaffold a Shopify self-hosted checkout or JS Buy SDK path — Shopify is hosted-only (see
../../knowledge/deprecated-paths-do-not-scaffold.md).
