claude-code-arcane 1.3.0 → 2.0.0

package/skills/personal-brand/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit
 ---
 
-# Personal Brand — Autoridad en LinkedIn para la búsqueda
+# Personal Brand - Autoridad en LinkedIn para la búsqueda
 
 Construís una marca personal en LinkedIn orientada a conseguir trabajo: un backlog **secuenciado** de ideas de post (ritmo 1/día) que construye autoridad y credibilidad *antes* de salir a hacer outreach, de modo que cuando escribas a un recruiter ya tengan contexto de quién sos.
 
@@ -15,25 +15,25 @@ Trabajás contra el **perfil maestro** (`01-Perfiles/`) y el rol/empresas objeti
 
 ## Los 4 pilares
 
-1. **Builder credibility** — qué construiste/entregaste, con resultados. Demuestra que hacés, no solo que sabés.
-2. **Lessons from current role** — aprendizajes concretos del trabajo actual/reciente (técnicos y de proceso).
-3. **POVs on your domain** — opiniones/tendencias de tu dominio. Te posiciona como alguien que piensa, no solo ejecuta.
-4. **Behind-the-scenes of the job search** — el viaje de la búsqueda (en su justa medida): genera cercanía y a veces atrae oportunidades directas.
+1. **Builder credibility** - qué construiste/entregaste, con resultados. Demuestra que hacés, no solo que sabés.
+2. **Lessons from current role** - aprendizajes concretos del trabajo actual/reciente (técnicos y de proceso).
+3. **POVs on your domain** - opiniones/tendencias de tu dominio. Te posiciona como alguien que piensa, no solo ejecuta.
+4. **Behind-the-scenes of the job search** - el viaje de la búsqueda (en su justa medida): genera cercanía y a veces atrae oportunidades directas.
 
 Ver `references/post-pillars.md` para ángulos, hooks y formatos por pilar.
 
 ## Modos
 
-### `plan` — Backlog de 90 ideas secuenciadas
+### `plan` - Backlog de 90 ideas secuenciadas
 1. Confirmar rol objetivo, empresas y los temas donde el usuario tiene autoridad real (del perfil maestro).
 2. Generar **90 ideas** repartidas en los 4 pilares. Cada idea = **hook + ángulo + formato** (texto, carrusel, lista, story, hot-take).
-3. **Secuenciar**: los primeros ~30 días priorizan pilares 1–3 (construir autoridad); recién después meter más del pilar 4 y empujar el outreach. La autoridad va antes que el pedido.
+3. **Secuenciar**: los primeros ~30 días priorizan pilares 1-3 (construir autoridad); recién después meter más del pilar 4 y empujar el outreach. La autoridad va antes que el pedido.
 4. Entregar como tabla/calendario (día → idea → pilar → formato).
 
-### `ideas <N>` — Lote de N ideas
+### `ideas <N>` - Lote de N ideas
 Generar N ideas frescas para un pilar o tema puntual, mismo formato hook+ángulo+formato.
 
-### `draft <idea>` — Escribir un post
+### `draft <idea>` - Escribir un post
 Convertir una idea en un post listo para publicar: hook fuerte en la primera línea, cuerpo escaneable, CTA o pregunta de cierre. Tono humano, sin clichés de LinkedIn ("I'm humbled to announce…").
 
 ## Principios
@@ -43,7 +43,7 @@ Convertir una idea en un post listo para publicar: hook fuerte en la primera lí
 - **Una idea por post.** Foco.
 - **Consistencia > perfección.** El plan asume ritmo sostenible; mejor 1/día simple que 1/semana elaborado.
 - **Autoridad antes que pedido.** No arranques pidiendo trabajo; primero aportá valor.
-- **Verdad.** Nada de logros inflados — la audiencia y los recruiters lo notan.
+- **Verdad.** Nada de logros inflados - la audiencia y los recruiters lo notan.
 
 ## Idioma
 

package/skills/personal-brand/references/post-pillars.md

@@ -1,17 +1,17 @@
-# Post Pillars — Ángulos, hooks y formatos
+# Post Pillars - Ángulos, hooks y formatos
 
 Guía para generar ideas con sustancia por cada uno de los 4 pilares. Cada idea final = **hook + ángulo + formato**.
 
 ## Formatos disponibles
 
-- **Text post corto** — 1 idea, 3–6 líneas, hook fuerte.
-- **Lista / "X things"** — escaneable, alto guardado.
-- **Carrusel** — paso a paso o framework (si el usuario hace slides).
-- **Hot take / POV** — opinión con tensión, invita a debate.
-- **Story / mini-caso** — situación → acción → resultado (mini-STAR público).
-- **Pregunta** — abre conversación, sube engagement.
+- **Text post corto** - 1 idea, 3-6 líneas, hook fuerte.
+- **Lista / "X things"** - escaneable, alto guardado.
+- **Carrusel** - paso a paso o framework (si el usuario hace slides).
+- **Hot take / POV** - opinión con tensión, invita a debate.
+- **Story / mini-caso** - situación → acción → resultado (mini-STAR público).
+- **Pregunta** - abre conversación, sube engagement.
 
-## Pilar 1 — Builder credibility
+## Pilar 1 - Builder credibility
 
 Demostrar que entregás. Ángulos:
 - Un problema real que resolviste + el número de impacto.
@@ -21,7 +21,7 @@ Demostrar que entregás. Ángulos:
 
 Hooks ejemplo: *"Bajé la latencia de matchmaking 25%. El cambio que más movió la aguja no fue el que esperaba."*
 
-## Pilar 2 — Lessons from current role
+## Pilar 2 - Lessons from current role
 
 Aprendizajes concretos, no abstractos. Ángulos:
 - Un error que cometiste y qué cambiaste.
@@ -31,7 +31,7 @@ Aprendizajes concretos, no abstractos. Ángulos:
 
 Hooks ejemplo: *"Pasé 2 años optimizando lo que no importaba. Esto es lo que mido ahora."*
 
-## Pilar 3 — POVs on your domain
+## Pilar 3 - POVs on your domain
 
 Posicionarte como alguien que piensa el dominio. Ángulos:
 - Una tendencia y por qué estás de acuerdo / en contra.
@@ -41,7 +41,7 @@ Posicionarte como alguien que piensa el dominio. Ángulos:
 
 Hooks ejemplo: *"Todos dicen que [tendencia]. En producción, lo que veo es otra cosa."*
 
-## Pilar 4 — Behind-the-scenes del job search
+## Pilar 4 - Behind-the-scenes del job search
 
 Cercanía + a veces atrae ofertas directas. Usar con medida (no quejas). Ángulos:
 - Qué buscás y por qué (señal clara para recruiters).
@@ -53,9 +53,9 @@ Hooks ejemplo: *"Estoy buscando mi próximo rol como [rol]. Esto es exactamente
 
 ## Secuenciación (90 días)
 
-- **Días 1–30 (autoridad):** ~70% pilares 1–3, ~30% pilar 2. Casi nada de "busco trabajo" todavía — primero construís credibilidad.
-- **Días 31–60 (visibilidad + señal):** introducir pilar 4 (qué buscás), mantener 1–3. Empezar outreach (`/cold-outreach`) apoyado en los posts.
-- **Días 61–90 (conversión):** mezclar los 4, más casos de builder credibility, CTAs suaves hacia conversaciones.
+- **Días 1-30 (autoridad):** ~70% pilares 1-3, ~30% pilar 2. Casi nada de "busco trabajo" todavía - primero construís credibilidad.
+- **Días 31-60 (visibilidad + señal):** introducir pilar 4 (qué buscás), mantener 1-3. Empezar outreach (`/cold-outreach`) apoyado en los posts.
+- **Días 61-90 (conversión):** mezclar los 4, más casos de builder credibility, CTAs suaves hacia conversaciones.
 
 ## Anti-patrones
 

package/skills/portfolio-site/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit, WebFetch
 ---
 
-# Portfolio Site — Portfolio web desde el source-of-truth
+# Portfolio Site - Portfolio web desde el source-of-truth
 
 Generás o actualizás un **portfolio web personal** a partir de un único source-of-truth (`portfolio/Datos Portfolio Web.md` en el career workspace, derivado del perfil maestro). La regla: **el contenido se edita primero en el `.md`** y de ahí se sincroniza al sitio.
 
@@ -19,7 +19,7 @@ Convención: **valores en inglés** (van directo al sitio) y meta-instrucciones
 
 ## Modos
 
-### `sync` — Actualizar un portfolio existente
+### `sync` - Actualizar un portfolio existente
 Para cuando ya hay un repo de portfolio (ej. una React SPA con el contenido en `src/pages/*.js`, `src/data/*`, o similar).
 
 1. Leer el source-of-truth y el repo destino.
@@ -28,10 +28,10 @@ Para cuando ya hay un repo de portfolio (ej. una React SPA con el contenido en `
 4. Aplicar los cambios al sitio respetando su arquitectura y estilo de código existentes.
 5. Verificar (build/preview) y resumir el diff.
 
-### `scaffold` — Crear un portfolio nuevo
+### `scaffold` - Crear un portfolio nuevo
 Para cuando no hay sitio todavía.
 
-1. Preguntar el stack preferido (default sugerido: **sitio estático simple** — HTML/CSS o un framework liviano como Astro/Vite — fácil de hostear en GitHub Pages/Netlify).
+1. Preguntar el stack preferido (default sugerido: **sitio estático simple** - HTML/CSS o un framework liviano como Astro/Vite - fácil de hostear en GitHub Pages/Netlify).
 2. Preguntar secciones deseadas (hero, about, experiencia, proyectos, skills, contacto).
 3. Generar el proyecto consumiendo el source-of-truth como contenido.
 4. Configurar deploy (GitHub Pages / Netlify) si el usuario quiere.
@@ -39,18 +39,18 @@ Para cuando no hay sitio todavía.
 
 ## Secciones típicas
 
-- **Hero** — nombre, headline, bio corto, links (GitHub/LinkedIn/email público).
-- **About** — bio medio/largo.
-- **Experience** — roles con highlights.
-- **Projects** — los destacados, con tech, descripción corta y link en vivo.
-- **Skills** — agrupados, con nivel/%.
-- **Contact** — email **público** (nunca el personal), formulario o links.
+- **Hero** - nombre, headline, bio corto, links (GitHub/LinkedIn/email público).
+- **About** - bio medio/largo.
+- **Experience** - roles con highlights.
+- **Projects** - los destacados, con tech, descripción corta y link en vivo.
+- **Skills** - agrupados, con nivel/%.
+- **Contact** - email **público** (nunca el personal), formulario o links.
 
 ## Reglas
 
 - **El `.md` es la fuente.** Nunca editar el sitio sin reflejarlo en el source-of-truth (si no, vuelve el drift).
 - Email **público** en el sitio, jamás el personal/teléfono.
-- Respetar la arquitectura y el estilo del repo existente en modo `sync` — no reescribir todo.
+- Respetar la arquitectura y el estilo del repo existente en modo `sync` - no reescribir todo.
 - En `scaffold`, mantenerlo simple y rápido de hostear salvo que el usuario pida otra cosa.
 - No subir datos sensibles; el portfolio es público.
 

package/skills/product-listing/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: product-listing
+description: "Optimize product detail pages and marketplace listings for discovery and conversion — titles, bullets, descriptions, imagery, A+ content, and marketplace algorithms (Amazon A10/COSMO/Rufus). Includes bulk-copy generation guidance. Triggers: writing/optimizing PDP copy, marketplace listings, bulk product descriptions."
+argument-hint: "[pdp | marketplace | bulk]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Product Listing
+
+A listing has two readers: the ranking algorithm and the buyer. Optimize for both — keyword-relevant enough to surface, persuasive enough to convert — across your own PDP and marketplaces.
+
+## Before Starting
+
+Gather: channel (own store vs Amazon/Meta/etc.), product category and key attributes, target keywords, and goal (optimize a PDP, write a marketplace listing, or generate bulk descriptions).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **PDP** | `pdp` | Optimized own-store product page copy |
+| **Marketplace** | `marketplace` | Channel-specific listing (title/bullets/A+) |
+| **Bulk** | `bulk` | Templated copy for many SKUs at scale |
+
+---
+
+## Phase 1 — PDP Copy Anatomy
+
+| Element | Rule |
+|---------|------|
+| **Title** | Brand + product + key differentiator; front-load the noun |
+| **Bullets** | Benefit-led, scannable; feature → benefit translation |
+| **Description** | Story + specs; answer objections; structured for skim |
+| **Imagery** | Multiple angles, scale/context, zoom; alt text for SEO + a11y |
+| **Trust** | Reviews, ratings, returns, shipping, stock signals near the CTA |
+
+Map product attributes (from `commerce-data-model`) into structured spec tables — buyers filter on them and search engines index them.
+
+---
+
+## Phase 2 — Marketplace Algorithms
+
+Marketplace listings must satisfy ranking systems, not just shoppers:
+
+- **Amazon A10** — keyword/relevance + sales velocity + conversion. Put core keywords in title and bullets naturally.
+- **COSMO** — semantic/intent: write for *purchase intent and use-cases*, not just keyword stuffing.
+- **Rufus / AI assistants** — Q&A-friendly content: cover comparisons, compatibility, use-cases the way a shopper would ask.
+- Localize per marketplace (not just translate) — units, sizing, terminology.
+
+Avoid keyword stuffing; modern algorithms penalize it and shoppers distrust it. Hand SEO structure to `ai-seo` / `seo-audit`.
+
+---
+
+## Phase 3 — Bulk Generation
+
+For large catalogs, template the copy:
+
+1. Define a copy template per product category (slots: hook, benefits, specs, use-case).
+2. Map structured attributes → slots.
+3. Generate, then spot-QA for accuracy and duplicate-content risk (search engines penalize near-duplicates).
+
+Pair with `merchant-feed` (the script there validates the structured attributes that feed both listings and ads).
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| PDP | Title + bullets + description + image/alt brief |
+| Marketplace | Channel-tuned listing with keyword map |
+| Bulk | Category templates + slot mapping |
+
+A listing is **READY** when the title front-loads the product, bullets are benefit-led, intent/use-cases are covered for AI search, trust signals sit by the CTA, and there's no duplicate-content risk.
+
+---
+
+## Related Skills
+
+- **commerce-data-model**: source of the structured attributes copy draws on.
+- **ai-seo** / **seo-audit** / **schema-markup**: organic discovery and markup.
+- **merchant-feed**: same attributes power shopping ads.
+- **copywriting** / **page-cro**: deeper persuasion and conversion testing.

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.