Forge playbook — E-commerce / store / digital products
Storefront UI defers to forge-website; anything that charges a card defers to forge-payments (this playbook never re-implements card handling). This file owns the commerce-specific concerns: catalog, cart, inventory correctness, orders, and connectors. Forge context: CASHFLOWWW / Moneymaker / Etsy-style shops.
Hard rules
- Real product/listing data with honest empty states. No lorem/placeholder products passed off as a real catalog; an empty catalog renders a real empty state, never fake inventory or fabricated sales/metrics.
- Oversell-safe inventory. Stock decrement is an atomic conditional update ("first writer wins",
UPDATE ... SET stock = stock - qty WHERE stock >= qty) or a reservation row — never a read-then-write that races. Concurrent buyers of the last unit → exactly one succeeds. Prefer soft-reserve at cart/checkout intake, hard-decrement at order confirmation.
- Idempotent order creation.
POST /order (or checkout submit) carries an Idempotency-Key with a UNIQUE constraint, because mobile networks retry, users double-tap, and gateways time out — a duplicate submit must return the same order, not create two. (Same pattern as forge-payments; keep them consistent.)
- Connectors gated until keys + approval. Store/marketplace connectors (Shopify Admin, WooCommerce, Etsy, Stripe) stay disabled until real keys are present AND the owner approves. No live publish, store-push, listing update, price change, or spend without explicit owner approval.
- Money = integer minor units + currency (see
forge-payments); no float math on prices, tax, shipping, or discounts.
- Secrets (store API keys, webhook secrets) in env +
.env.example placeholders only.
Team (conditional)
Lead: build-boss (full store) or integration-boss (connector/sync-only). Specialists: payment-integration (checkout/charge — via forge-payments), database-reviewer (inventory + order schema, race-safety), silent-failure-hunter (a dropped inventory sync or swallowed order error looks like a clean sale), typescript-reviewer / python-reviewer. Storefront: forge-website team (a11y, responsive, real content). Optional: codex-reviewer on the checkout/order/inventory paths.
Skills / commands / MCP
forge-website (storefront, product pages, cart UI), forge-payments (checkout + billing), forge-integration / forge-n8n (connector sync, order-notification automations). Store MCP/SDK docs via Context7 for exact connector APIs. Draft-only for any customer outreach (order emails staged, not blasted — shared with forge-integration).
Fan-out & flow
L2 catalog + cart; L3 catalog + cart + checkout + inventory + orders + a connector; L4 multi-channel store with marketplace sync.
Parallel: catalog/product pages ∥ cart logic ∥ inventory service ∥ storefront UI (independent once the product + order schema/contract is fixed).
Serial: data model (products, SKUs, minor-units prices, inventory) → catalog → cart → checkout (forge-payments) → atomic inventory decrement → order record → fulfillment/notification.
Domain gates
- Real catalog data or an honest empty state; no fabricated sales/inventory/metrics.
- Inventory decrement is atomic/reservation-based and proven oversell-safe under a concurrent-buyer test.
- Order creation is idempotent (unique idempotency key); a double-submit returns one order.
- Prices/tax/shipping in integer minor units; no float money math; totals reconcile.
- Cart → checkout → order → payment flow works end-to-end in test mode (an integration test, not just green units).
- Connectors inactive until keys + owner approval; no live publish/push/spend performed.
- Customer-facing emails/messages drafted, not auto-sent, without confirmation; idempotency before any order notification (no duplicate "order confirmed" mails on webhook retry).
Ship-readiness (unique)
Real products with honest empty state; one real purchase flow works end-to-end in test mode; oversell-safe inventory proven under concurrency; idempotent orders proven under double-submit; minor-units money reconciles; store connectors gated + no live push/spend done; order notifications idempotent + draft-gated; secrets in env. Advisory checklist; optionally run codex-reviewer on checkout/order/inventory — not a blocker; if a live store/marketplace action was requested, it stays owner-gated.
1---2name: forge-ecommerce3description: Forge playbook for e-commerce and cashflow shops. Use for shop, store, cart, checkout, product, inventory, Shopify, WooCommerce, Etsy, Stripe, order fulfillment, oversell.4---56# Forge playbook — E-commerce / store / digital products78Storefront UI defers to `forge-website`; anything that charges a card defers to **`forge-payments`** (this playbook never re-implements card handling). This file owns the commerce-specific concerns: catalog, cart, inventory correctness, orders, and connectors. Forge context: CASHFLOWWW / Moneymaker / Etsy-style shops.910## Hard rules11- **Real product/listing data with honest empty states.** No lorem/placeholder products passed off as a real catalog; an empty catalog renders a real empty state, never fake inventory or fabricated sales/metrics.12- **Oversell-safe inventory.** Stock decrement is an **atomic conditional update** ("first writer wins", `UPDATE ... SET stock = stock - qty WHERE stock >= qty`) or a reservation row — never a read-then-write that races. Concurrent buyers of the last unit → exactly one succeeds. Prefer soft-reserve at cart/checkout intake, hard-decrement at order confirmation.13- **Idempotent order creation.** `POST /order` (or checkout submit) carries an `Idempotency-Key` with a UNIQUE constraint, because mobile networks retry, users double-tap, and gateways time out — a duplicate submit must return the same order, not create two. (Same pattern as `forge-payments`; keep them consistent.)14- **Connectors gated until keys + approval.** Store/marketplace connectors (Shopify Admin, WooCommerce, Etsy, Stripe) stay disabled until real keys are present AND the owner approves. **No live publish, store-push, listing update, price change, or spend without explicit owner approval.**15- **Money = integer minor units + currency** (see `forge-payments`); no float math on prices, tax, shipping, or discounts.16- Secrets (store API keys, webhook secrets) in env + `.env.example` placeholders only.1718## Team (conditional)19Lead: `build-boss` (full store) or `integration-boss` (connector/sync-only). Specialists: `payment-integration` (checkout/charge — via `forge-payments`), `database-reviewer` (inventory + order schema, race-safety), `silent-failure-hunter` (a dropped inventory sync or swallowed order error looks like a clean sale), `typescript-reviewer` / `python-reviewer`. Storefront: `forge-website` team (a11y, responsive, real content). Optional: `codex-reviewer` on the checkout/order/inventory paths.2021## Skills / commands / MCP22`forge-website` (storefront, product pages, cart UI), `forge-payments` (checkout + billing), `forge-integration` / `forge-n8n` (connector sync, order-notification automations). Store MCP/SDK docs via Context7 for exact connector APIs. Draft-only for any customer outreach (order emails staged, not blasted — shared with `forge-integration`).2324## Fan-out & flow25L2 catalog + cart; L3 catalog + cart + checkout + inventory + orders + a connector; L4 multi-channel store with marketplace sync.26**Parallel:** catalog/product pages ∥ cart logic ∥ inventory service ∥ storefront UI (independent once the product + order schema/contract is fixed).27**Serial:** data model (products, SKUs, minor-units prices, inventory) → catalog → cart → checkout (`forge-payments`) → atomic inventory decrement → order record → fulfillment/notification.2829## Domain gates30- Real catalog data or an honest empty state; no fabricated sales/inventory/metrics.31- Inventory decrement is atomic/reservation-based and proven oversell-safe under a concurrent-buyer test.32- Order creation is idempotent (unique idempotency key); a double-submit returns one order.33- Prices/tax/shipping in integer minor units; no float money math; totals reconcile.34- Cart → checkout → order → payment flow works end-to-end in test mode (an integration test, not just green units).35- Connectors inactive until keys + owner approval; no live publish/push/spend performed.36- Customer-facing emails/messages drafted, not auto-sent, without confirmation; idempotency before any order notification (no duplicate "order confirmed" mails on webhook retry).3738## Ship-readiness (unique)39Real products with honest empty state; one real purchase flow works end-to-end in test mode; oversell-safe inventory proven under concurrency; idempotent orders proven under double-submit; minor-units money reconciles; store connectors gated + no live push/spend done; order notifications idempotent + draft-gated; secrets in env. Advisory checklist; optionally run `codex-reviewer` on checkout/order/inventory — not a blocker; if a live store/marketplace action was requested, it stays owner-gated.
ForgeyClap