claude-code-arcane 1.2.0 → 1.4.0

package/skills/promotions-discounts/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: promotions-discounts
+description: "Design a promotions and discount engine — coupon codes, automatic discounts, BOGO, tiered/volume pricing, stacking and exclusivity rules, and gift cards. Platform-agnostic rules modeling that avoids margin leaks. Triggers: designing discounts, defining stacking rules, modeling gift cards/coupons."
+argument-hint: "[design | rules | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Promotions & Discounts
+
+Discounts are easy to add and hard to control. Model the rules so promotions stack predictably, can't be abused, and never quietly destroy margin — independent of platform.
+
+## Before Starting
+
+Gather: promotion types in use, who can stack with what, abuse history (code sharing, repeat redemption), and goal (design the engine, define stacking/exclusivity rules, or audit existing promos for leaks).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Discount engine model + rule schema |
+| **Rules** | `rules` | Stacking, exclusivity, and eligibility matrix |
+| **Audit** | `audit` | Margin-leak and abuse-risk review |
+
+---
+
+## Phase 1 — Discount Model
+
+Model every promotion as **trigger → condition → effect → constraints**:
+
+| Part | Examples |
+|------|----------|
+| **Trigger** | code entered, automatic, cart threshold |
+| **Condition** | min subtotal, specific collection, customer segment, first order |
+| **Effect** | % off, fixed off, free shipping, BOGO, fixed price |
+| **Constraints** | usage cap (global/per-customer), date window, exclusivity |
+
+**Rule:** Discounts apply to a defined scope (line / shipping / order) and are recomputed server-side at checkout — never client-trusted.
+
+---
+
+## Phase 2 — Stacking & Exclusivity
+
+The hard part. Define explicitly:
+
+- **Stackable vs exclusive:** most stores allow one order-level code; auto-discounts may stack with codes. Decide and enforce.
+- **Application order** matters for % vs fixed — define it (typically line discounts → order discounts → shipping).
+- **Priority** when multiple eligible: best-for-customer vs best-for-merchant — pick a policy.
+- **Caps:** max discount per order; floor on post-discount margin.
+
+For the full eligibility matrix and worked stacking examples, model the matrix per the table above.
+
+---
+
+## Phase 3 — Gift Cards & Abuse Prevention
+
+- **Gift cards** are stored-value tender, not discounts — track balance, partial redemption, and never let balance go negative or expire silently where regulated.
+- **Abuse defenses:** per-customer usage caps, one-time codes, segment gating, and minimum-order thresholds. Watch for code leaks to coupon sites.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Rule schema + effect/scope model |
+| Rules | Stacking/exclusivity matrix + application order |
+| Audit | Leak/abuse findings: PASS / CONCERNS / FAIL |
+
+A promotion engine is **COMPLIANT** when discounts are server-computed, stacking and application order are explicit, usage caps are enforced, and a margin floor protects every order.
+
+---
+
+## Related Skills
+
+- **cart-checkout**: applies discounts at the cart/checkout.
+- **pricing-strategy**: sets the base prices discounts modify.
+- **commerce-analytics**: measures promo ROI and margin impact.
+- **referral-program**: a specialized promotion type.

package/skills/shipping-tax/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: shipping-tax
+description: "Design shipping and tax logic — shipping zones, rates and methods, carrier integration patterns, plus sales tax/VAT/GST, nexus, and duties. Platform-agnostic rules for correct totals at checkout. Triggers: designing shipping rates, modeling tax/VAT, handling cross-border duties."
+argument-hint: "[shipping | tax | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Shipping & Tax
+
+The two line items most likely to be wrong at checkout — and the ones that cause chargebacks, abandoned carts, and compliance trouble. Model them correctly and computed server-side, independent of platform.
+
+## Before Starting
+
+Gather: markets shipped to/from, carriers, product attributes (weight/dims), tax obligations (countries, nexus, registrations), and goal (design shipping, design tax, or audit existing totals).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Shipping** | `shipping` | Zones, methods, and rate model |
+| **Tax** | `tax` | Tax determination and nexus model |
+| **Audit** | `audit` | Correctness review of current totals |
+
+---
+
+## Phase 1 — Shipping Model
+
+Layer the model as **zones → methods → rates**:
+
+| Layer | Definition |
+|-------|-----------|
+| **Zone** | Geographic grouping (country/region/postal ranges) |
+| **Method** | Service level (standard, express, pickup) per zone |
+| **Rate** | flat / weight-based / price-based / carrier-calculated / free-over-threshold |
+
+- **Free-shipping thresholds** must be computed on the discounted subtotal.
+- **Carrier-calculated** rates need weight + dimensions on the variant — falls back to flat if missing.
+- Show shipping before the payment step; recompute when the address changes.
+
+---
+
+## Phase 2 — Tax Determination
+
+Tax is destination- and product-dependent — never a single flat rate:
+
+| Concept | Rule |
+|---------|------|
+| **Nexus** | You only collect where you have an obligation — model registrations per jurisdiction |
+| **Destination vs origin** | Most VAT/GST is destination-based; some US states origin-based |
+| **Product taxability** | Categories differ (food, digital, apparel) — map products to tax categories |
+| **Price display** | Tax-inclusive (EU/UK) vs tax-exclusive (US) — a presentation rule, get it right per market |
+| **B2B** | Reverse-charge / VAT-ID validation for cross-border EU |
+
+**Rule:** Compute tax at checkout against the shipping destination, using a tax category per product. Round per jurisdiction rules.
+
+---
+
+## Phase 3 — Cross-Border & Duties
+
+- **DDP vs DDU:** decide who pays import duties — DDP (you collect at checkout, best UX) vs DDU (customer pays on delivery, surprise fees → returns).
+- **Landed cost** = item + shipping + duties + tax; show it for cross-border.
+- Capture **HS codes** and country of origin on products for customs.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Shipping | Zone/method/rate model |
+| Tax | Nexus map + product tax-category mapping |
+| Audit | Findings per market: PASS / FAIL with fixes |
+
+Shipping and tax are **READY** when both are computed server-side against the destination, free-shipping uses discounted subtotals, tax categories are mapped, and cross-border shows landed cost.
+
+---
+
+## Related Skills
+
+- **cart-checkout**: displays and recomputes these at the shipping step.
+- **order-lifecycle**: shipping method feeds fulfillment; tax recorded on the order.
+- **commerce-data-model**: weight/dims/HS code/tax category live on the product.
+- **merchant-feed**: shipping and tax attributes appear in product feeds.

package/skills/storefront-architecture/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: storefront-architecture
+description: "Design storefront information architecture and the page system — homepage, listing (PLP), product detail (PDP), cart, checkout, search and navigation/megamenu — plus the headless-vs-monolith decision and performance budgets. Stack-agnostic. Triggers: planning a storefront, choosing headless vs monolith, designing navigation/search."
+argument-hint: "[design | pages | headless]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Storefront Architecture
+
+The shopper-facing structure: how pages, navigation, and search fit together, and what platform shape to build on. Decisions here, not code — applicable to any framework.
+
+## Before Starting
+
+Gather: catalog size and complexity, content needs (editorial, localization), team/stack constraints, and goal (design the IA, spec the page system, or make the headless-vs-monolith call).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Full IA + page system + nav/search plan |
+| **Pages** | `pages` | Per-page-type component and content spec |
+| **Headless** | `headless` | Architecture decision with trade-offs |
+
+---
+
+## Phase 1 — The Page System
+
+| Page type | Job | Must have |
+|-----------|-----|-----------|
+| **Home** | Orient + route | Value prop, primary nav, featured collections |
+| **PLP** (listing) | Browse + filter | Facets, sort, pagination, quick-add |
+| **PDP** (detail) | Convert | Gallery, variant selector, price, stock, CTA, trust signals |
+| **Search** | Find | Autocomplete, typo tolerance, zero-result handling |
+| **Cart** | Review | Editable lines, totals, clear CTA |
+| **Checkout** | Pay | Owned by `cart-checkout` |
+
+PDP and PLP are driven by the `commerce-data-model` (variants, attributes, facets).
+
+---
+
+## Phase 2 — Navigation & Search
+
+- **Megamenu** mirrors the taxonomy (categories → subcategories), not collections. Keep depth ≤ 3.
+- **Search** is a primary nav path, not a fallback — invest in autocomplete and synonyms.
+- Stable, human-readable URLs per category/product (SEO; hand off to `seo-audit` / `schema-markup`).
+
+---
+
+## Phase 3 — Platform Shape & Performance
+
+| Option | Best for | Cost |
+|--------|----------|------|
+| **Monolith** (SaaS/themed) | Speed to market, standard catalogs | Less flexibility |
+| **Headless** (decoupled FE) | Custom UX, omnichannel, scale | Higher build/ops cost |
+| **Composable** | Enterprise, best-of-breed | Integration complexity |
+
+**Performance budget** (Core Web Vitals): PDP/PLP LCP < 2.5s, lazy-load below-fold imagery, prioritize the variant/price/CTA above the fold. Performance is a conversion factor, not a nice-to-have.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | IA map + page system + nav/search plan |
+| Pages | Component/content spec per page type |
+| Headless | Decision matrix + recommendation |
+
+A storefront architecture is **READY** when each page type has a clear job and component spec, navigation mirrors the taxonomy, search is first-class, and a performance budget is defined.
+
+---
+
+## Related Skills
+
+- **commerce-data-model**: feeds PLP/PDP structure.
+- **cart-checkout**: owns the cart and checkout pages.
+- **site-architecture** / **seo-audit** / **schema-markup**: SEO structure and markup.
+- **page-cro**: conversion optimization of the page templates.

package/skills/subscription-billing/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: subscription-billing
+description: "Design recurring billing for commerce — subscription models, billing cycles, proration, trials, plan changes, and dunning/recovery for involuntary churn. Processor-agnostic; hands implementation to processor-specific skills. Triggers: designing subscriptions, modeling proration/plan changes, reducing involuntary churn via dunning."
+argument-hint: "[design | dunning | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Subscription Billing
+
+Recurring revenue adds a time dimension that one-time commerce never faces: cycles, proration, failed renewals, and dunning. Model it correctly so revenue is predictable and involuntary churn doesn't quietly bleed the business — independent of processor.
+
+## Before Starting
+
+Gather: offering (subscribe-and-save, membership, SaaS-style tiers), billing cadence, trial/plan-change rules, and goal (design the model, design dunning/recovery, or audit existing billing).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Subscription + cycle + proration model |
+| **Dunning** | `dunning` | Failed-payment recovery flow |
+| **Audit** | `audit` | Revenue-leak and churn-risk review |
+
+---
+
+## Phase 1 — Subscription Model
+
+| Concept | Decision |
+|---------|----------|
+| **Plan** | Price + interval + included entitlements |
+| **Cycle** | Anchor date; calendar vs signup-aligned |
+| **Trial** | Free / paid / card-required — and what happens at trial end |
+| **Proration** | On upgrade/downgrade: credit unused time, charge difference |
+| **State** | active → past_due → cancelled / paused / expired |
+
+**Rule:** A subscription is a state machine over time — model `past_due` explicitly; it's where recoverable revenue lives. Reuse `order-lifecycle` thinking for state/events.
+
+---
+
+## Phase 2 — Proration & Plan Changes
+
+- **Upgrade:** charge prorated difference immediately or at next cycle — pick a policy and state it.
+- **Downgrade:** typically defer to next cycle (avoid refund complexity).
+- **Pause/skip:** common in physical subscribe-and-save; preserve the schedule.
+- Always show the customer the next charge amount and date before confirming a change.
+
+---
+
+## Phase 3 — Dunning & Involuntary Churn
+
+Most subscription churn is **involuntary** — failed card charges, not cancellations. Recover it:
+
+1. **Smart retries** — retry on a schedule (e.g. day 1, 3, 5, 7), not immediately; align to paydays where known.
+2. **Pre-dunning** — warn before card expiry; prompt card update.
+3. **Dunning emails** — escalating sequence during `past_due` with a one-click update link.
+4. **Grace period** — keep access during retries; downgrade/cancel only after the window.
+
+Processor specifics (retry config, webhooks) hand off to `stripe-integration-expert`.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Plan/cycle/proration/state model |
+| Dunning | Retry schedule + email sequence + grace policy |
+| Audit | Leak/churn findings: PASS / CONCERNS / FAIL |
+
+A subscription billing design is **COMPLETE** when `past_due` is modeled, proration policy is explicit, the customer always sees the next charge, and a dunning sequence recovers involuntary churn.
+
+---
+
+## Related Skills
+
+- **payments-architecture**: recurring charges and webhook reliability.
+- **stripe-integration-expert**: processor-specific subscription implementation.
+- **churn-prevention**: voluntary-churn (cancellation) reduction.
+- **commerce-analytics**: MRR, retention, and recovery metrics.