claude-code-arcane 1.3.0 → 2.0.0

package/skills/master-profile/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: master-profile
-description: "Build and maintain the master professional profile — the single source of truth (experience, skills with levels, projects, education, references, bios) that every CV, LinkedIn profile and portfolio derives from. Triggers: perfil maestro, master resume, cronologia laboral, single source of truth CV, mi experiencia profesional."
+description: "Build and maintain the master professional profile - the single source of truth (experience, skills with levels, projects, education, references, bios) that every CV, LinkedIn profile and portfolio derives from. Triggers: perfil maestro, master resume, cronologia laboral, single source of truth CV, mi experiencia profesional."
 argument-hint: "[build | update | derive <role>]"
 category: "career"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit
 ---
 
-# Master Profile — Single Source of Truth
+# Master Profile - Single Source of Truth
 
 Construís y mantenés el **perfil maestro**: el documento del que derivan todos los CVs, el LinkedIn y el portfolio. La regla de oro: **si algo cambia, se cambia acá primero** y de acá se sincroniza al resto.
 
@@ -21,32 +21,32 @@ Mantener N CVs sincronizados a mano es la causa #1 de errores (fechas que no coi
 
 Generá el archivo con estas secciones (todas las que apliquen):
 
-1. **Personal info** — nombre, display name, headline actual, ubicación, email público vs personal, teléfono, LinkedIn, GitHub, portfolio. (El email *público* puede diferir del personal.)
-2. **Bios** — tres largos: corto (hero/one-liner), medio (2–3 oraciones para "About"), largo (about page completo).
-3. **Work experience** (más reciente primero) — por cada rol: empresa, período, ubicación/modalidad, producto, stack, manager/referencia, y **bullets de logros con número→contexto→resultado**.
-4. **Education** — institución, período, foco.
-5. **Certifications** — nombre, año, estado (completo/in progress).
-6. **Skills consolidados con nivel** — agrupados (lenguajes, frameworks, infra, tooling) con nivel (Expert/Advanced/Proficient/…) y opcionalmente % para el portfolio.
-7. **Projects** — tech, rol, highlights, link en vivo.
-8. **Achievements / highlights** — premios, showcases, hitos.
-9. **Languages** — idioma + nivel.
-10. **References** — nombre, rol, relación, contacto.
+1. **Personal info** - nombre, display name, headline actual, ubicación, email público vs personal, teléfono, LinkedIn, GitHub, portfolio. (El email *público* puede diferir del personal.)
+2. **Bios** - tres largos: corto (hero/one-liner), medio (2-3 oraciones para "About"), largo (about page completo).
+3. **Work experience** (más reciente primero) - por cada rol: empresa, período, ubicación/modalidad, producto, stack, manager/referencia, y **bullets de logros con número→contexto→resultado**.
+4. **Education** - institución, período, foco.
+5. **Certifications** - nombre, año, estado (completo/in progress).
+6. **Skills consolidados con nivel** - agrupados (lenguajes, frameworks, infra, tooling) con nivel (Expert/Advanced/Proficient/…) y opcionalmente % para el portfolio.
+7. **Projects** - tech, rol, highlights, link en vivo.
+8. **Achievements / highlights** - premios, showcases, hitos.
+9. **Languages** - idioma + nivel.
+10. **References** - nombre, rol, relación, contacto.
 
 ## Modos
 
-### `build` — Crear el maestro desde cero
+### `build` - Crear el maestro desde cero
 1. Si no existe el workspace, sugerir `/job-hunt setup` primero.
-2. Recolectar info por sección — preferí **entrevistar al usuario por bloques** (no un cuestionario gigante). Empezá por experiencia y skills.
+2. Recolectar info por sección - preferí **entrevistar al usuario por bloques** (no un cuestionario gigante). Empezá por experiencia y skills.
 3. Para cada logro, empujar a la forma **cuantificable**: "¿qué número podés ponerle? ¿comparado con qué? ¿qué resultado tuvo?". Un bullet sin métrica es una oportunidad perdida.
 4. Escribir `01-Perfiles/Perfil Maestro.md`.
 5. Sugerir derivar el primer perfil por rol: `/master-profile derive <role>`.
 
-### `update` — Mantener al día
+### `update` - Mantener al día
 1. Leer el maestro actual.
 2. Aplicar el cambio (nuevo rol, nuevo logro, ascenso, proyecto).
 3. **Avisar qué derivados quedan desactualizados** (CVs por rol, LinkedIn, portfolio) y ofrecer re-derivarlos.
 
-### `derive <role>` — Vista por rol
+### `derive <role>` - Vista por rol
 1. Leer el maestro.
 2. Crear/actualizar `01-Perfiles/<Role>.md` con el template `Perfil` (ver `Templates/Perfil.md`): filtrar y reordenar la experiencia/skills/proyectos hacia ese rol, definir keywords objetivo, score mínimo y mercado.
 3. Este perfil por rol es el `perfil_base` que después usa `/cv-tailor`.
@@ -61,7 +61,7 @@ Generá el archivo con estas secciones (todas las que apliquen):
 ## Reglas
 
 - Una sola fuente de verdad: no dejar que un CV por rol "evolucione" por fuera del maestro.
-- No inventar logros ni métricas — si el usuario no tiene el número, marcarlo como pendiente, no fabricarlo.
+- No inventar logros ni métricas - si el usuario no tiene el número, marcarlo como pendiente, no fabricarlo.
 - Separar email público de personal; no exponer datos sensibles en archivos que vayan a un remoto.
 
 ## Handoff

package/skills/merchant-feed/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: merchant-feed
+description: "Build and validate product feeds for shopping channels — Google Merchant Center and Meta Catalog — including required/recommended attributes, attribute mapping, and feed validation. Includes a feed validator/generator script. Triggers: building a product feed, fixing feed disapprovals, mapping catalog to feed attributes."
+argument-hint: "[validate | generate | map]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Merchant Feed
+
+Shopping ads and free listings live or die on feed quality. A clean, complete feed gets products approved and surfaced; a sloppy one gets disapprovals. Map your catalog to channel attributes and validate before upload — platform-agnostic.
+
+## Before Starting
+
+Gather: target channel (Google Merchant / Meta Catalog), source of truth (DB export, CSV, platform), product categories, and goal (validate an existing feed, generate one, or map catalog → feed attributes).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Validate** | `validate` | Pass/fail report against required attributes |
+| **Generate** | `generate` | Feed emitted from a source CSV |
+| **Map** | `map` | Catalog field → feed attribute mapping |
+
+---
+
+## Phase 1 — Required Attributes
+
+Google Merchant / Meta share a common core. Required for every item:
+
+| Attribute | Notes |
+|-----------|-------|
+| `id` | Stable, unique per variant (use SKU) |
+| `title` | Front-load product; ≤150 chars; match landing page |
+| `description` | Plain, accurate; no promo text/caps |
+| `link` | Canonical PDP URL |
+| `image_link` | Main image, meets resolution minimums |
+| `availability` | in_stock / out_of_stock / preorder |
+| `price` | With currency; must match landing page exactly |
+| `brand` | Required unless exempt category |
+| `gtin` / `mpn` | Required where a GTIN exists — improves matching |
+| `condition` | new / refurbished / used |
+
+**Rule:** Feed price and availability must **exactly match** the live PDP, or the item is disapproved and the account is penalized.
+
+---
+
+## Phase 2 — Validate / Generate
+
+Run the validator on a CSV export:
+
+```bash
+python skills/merchant-feed/scripts/feed_validate.py            # demo data
+python skills/merchant-feed/scripts/feed_validate.py feed.csv
+```
+
+It checks every row for required attributes, flags missing/empty values, validates `availability`/`condition` enums and price+currency format, and reports a per-row and summary verdict. For the full attribute reference and category-specific requirements, see [references/feed-attribute-map.md](references/feed-attribute-map.md).
+
+---
+
+## Phase 3 — Recommended Attributes & Quality
+
+Beyond required, these lift performance: `google_product_category`, `product_type`, `item_group_id` (links variants), `color`, `size`, `gender`, `age_group`, `sale_price`, `shipping`, `gtin`. Use `item_group_id` so variants cluster correctly — without it, variants compete as separate products.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Validate | Per-row + summary PASS / FAIL report |
+| Generate | Channel-ready feed file |
+| Map | Catalog → feed attribute mapping table |
+
+A feed is **READY** when every item has all required attributes, price/availability match the PDP, variants share an `item_group_id`, and GTINs are present where they exist.
+
+---
+
+## Related Skills
+
+- **commerce-data-model**: the catalog entities mapped into feed attributes.
+- **product-listing**: titles/descriptions reused between PDP and feed.
+- **shipping-tax**: shipping attribute values in the feed.
+- **schema-markup**: Product structured data complements the feed for organic.

package/skills/merchant-feed/references/feed-attribute-map.md

@@ -0,0 +1,47 @@
+# Product Feed — Attribute Reference & Catalog Mapping
+
+Maps the commerce data model to Google Merchant / Meta Catalog feed attributes. The `feed_validate.py` script enforces the required core.
+
+## Required attributes (every item)
+| Feed attribute | Source (data model) | Rule |
+|----------------|---------------------|------|
+| id | variant.sku | Stable, unique per variant |
+| title | product.title (+ variant) | Front-load product; ≤150 chars; match PDP |
+| description | product.description | Plain, accurate; no promo/ALL CAPS |
+| link | product URL | Canonical, absolute https |
+| image_link | main image | Absolute https; meets resolution min |
+| availability | variant stock | in_stock / out_of_stock / preorder / backorder |
+| price | variant.price | `"21.00 USD"` — matches PDP exactly |
+| brand | product.brand | Required unless exempt category |
+| condition | — | new / refurbished / used |
+
+## Strongly recommended
+| Feed attribute | Source | Why |
+|----------------|--------|-----|
+| gtin | variant.barcode | Improves matching / eligibility |
+| mpn | variant.mpn | Fallback when no GTIN |
+| item_group_id | product.id | Clusters variants (else they compete) |
+| google_product_category | category map | Taxonomy alignment |
+| product_type | primary_category | Your own taxonomy |
+| color / size / gender / age_group | attributes | Apparel facets |
+| sale_price | compare_at logic | Promo pricing |
+| shipping | shipping-tax rules | Overrides account settings |
+
+## Hard rules (disapproval triggers)
+- Feed **price + availability must match the live PDP** exactly.
+- No promotional text in `title`/`description` (no "Free shipping!", no emojis/caps).
+- `image_link` must resolve and meet the channel's minimum resolution.
+- Variants without a shared `item_group_id` are treated as separate products.
+
+## Worked example (CSV row)
+```csv
+id,title,description,link,image_link,availability,price,brand,condition,gtin,item_group_id
+ACME-TEE-RED-M,"Acme Cotton Tee — Red, Medium","Soft 100% cotton crew-neck tee.",https://shop.example.com/p/acme-tee-red-m,https://shop.example.com/img/acme-tee-red-m.jpg,in_stock,21.00 USD,Acme,new,0123456789012,ACME-TEE
+```
+
+## Verdict: READY when
+- [ ] All required attributes present and non-empty
+- [ ] price/availability match PDP
+- [ ] valid availability + condition enums
+- [ ] price formatted `amount ISO-currency`
+- [ ] variants share item_group_id; GTIN present where it exists

package/skills/merchant-feed/scripts/feed_validate.py

@@ -0,0 +1,140 @@
+"""
+feed_validate.py — Validate a product feed CSV against Google Merchant /
+Meta Catalog requirements (the shared required-attribute core).
+
+Checks every row for required attributes, empty values, valid enums
+(availability, condition), and price+currency formatting. Reports a per-row
+and summary verdict. No external dependencies; cross-platform.
+
+Usage:
+    python feed_validate.py               # built-in demo feed
+    python feed_validate.py feed.csv      # validate your feed
+    python feed_validate.py feed.csv --strict   # treat recommended as required
+
+CSV header (required attributes):
+    id,title,description,link,image_link,availability,price,brand,condition
+Recommended columns (warn if absent/empty): gtin, mpn, item_group_id,
+    google_product_category, sale_price
+"""
+
+import argparse
+import csv
+import re
+import sys
+
+
+REQUIRED = ["id", "title", "description", "link", "image_link",
+            "availability", "price", "brand", "condition"]
+RECOMMENDED = ["gtin", "mpn", "item_group_id", "google_product_category"]
+
+AVAILABILITY = {"in_stock", "out_of_stock", "preorder", "backorder"}
+CONDITION = {"new", "refurbished", "used"}
+# e.g. "21.00 USD" / "9.99 EUR"
+PRICE_RE = re.compile(r"^\d+(\.\d{1,2})?\s+[A-Z]{3}$")
+URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+TITLE_MAX = 150
+DESC_MAX = 5000
+
+
+DEMO_FEED = [
+    {"id": "ACME-TEE-RED-M", "title": "Acme Cotton Tee — Red, Medium",
+     "description": "Soft 100% cotton crew-neck tee.", "link": "https://shop.example.com/p/acme-tee-red-m",
+     "image_link": "https://shop.example.com/img/acme-tee-red-m.jpg", "availability": "in_stock",
+     "price": "21.00 USD", "brand": "Acme", "condition": "new",
+     "gtin": "0123456789012", "item_group_id": "ACME-TEE"},
+    # broken row: bad availability, bad price, missing brand, non-url image
+    {"id": "ACME-MUG-BLUE", "title": "Acme Mug", "description": "",
+     "link": "https://shop.example.com/p/acme-mug", "image_link": "acme-mug.jpg",
+     "availability": "available", "price": "9.99", "brand": "", "condition": "brand-new"},
+]
+
+
+def validate_row(row, idx, strict):
+    errors = []
+    warnings = []
+
+    for attr in REQUIRED:
+        if not (row.get(attr) or "").strip():
+            errors.append(f"missing required '{attr}'")
+
+    avail = (row.get("availability") or "").strip().lower()
+    if avail and avail not in AVAILABILITY:
+        errors.append(f"availability '{avail}' not in {sorted(AVAILABILITY)}")
+
+    cond = (row.get("condition") or "").strip().lower()
+    if cond and cond not in CONDITION:
+        errors.append(f"condition '{cond}' not in {sorted(CONDITION)}")
+
+    price = (row.get("price") or "").strip()
+    if price and not PRICE_RE.match(price):
+        errors.append(f"price '{price}' must be like '21.00 USD' (amount + ISO currency)")
+
+    for url_attr in ("link", "image_link"):
+        val = (row.get(url_attr) or "").strip()
+        if val and not URL_RE.match(val):
+            errors.append(f"{url_attr} '{val}' must be an absolute http(s) URL")
+
+    title = (row.get("title") or "").strip()
+    if len(title) > TITLE_MAX:
+        warnings.append(f"title > {TITLE_MAX} chars ({len(title)})")
+    if len(row.get("description") or "") > DESC_MAX:
+        warnings.append(f"description > {DESC_MAX} chars")
+
+    has_id_link = bool((row.get("item_group_id") or "").strip())
+    if not has_id_link:
+        warnings.append("no item_group_id (variants won't cluster)")
+    if not (row.get("gtin") or "").strip() and not (row.get("mpn") or "").strip():
+        warnings.append("no gtin/mpn (weakens product matching)")
+
+    if strict:
+        errors.extend(f"(strict) {w}" for w in warnings)
+        warnings = []
+    return errors, warnings
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Validate a Google/Meta product feed CSV.")
+    ap.add_argument("csv", nargs="?", help="feed CSV. Omit for demo data.")
+    ap.add_argument("--strict", action="store_true", help="treat recommended issues as failures")
+    args = ap.parse_args()
+
+    if args.csv:
+        try:
+            with open(args.csv, newline="", encoding="utf-8") as f:
+                rows = list(csv.DictReader(f))
+        except OSError as e:
+            print(f"[ERROR] cannot read {args.csv}: {e}")
+            sys.exit(1)
+    else:
+        print("[INFO] No CSV given - using built-in demo feed.\n")
+        rows = DEMO_FEED
+
+    if not rows:
+        print("[ERROR] feed is empty.")
+        sys.exit(1)
+
+    failed = 0
+    for idx, row in enumerate(rows):
+        errors, warnings = validate_row(row, idx, args.strict)
+        rid = row.get("id") or f"row{idx}"
+        if errors:
+            failed += 1
+            print(f"FAIL  {rid}")
+            for e in errors:
+                print(f"        - {e}")
+            for w in warnings:
+                print(f"        ~ {w}")
+        else:
+            print(f"PASS  {rid}")
+            for w in warnings:
+                print(f"        ~ {w}")
+
+    print()
+    passed = len(rows) - failed
+    verdict = "READY" if failed == 0 else "NOT-READY"
+    print(f"{verdict}: {passed}/{len(rows)} items pass required-attribute checks.")
+    sys.exit(0 if failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/network-map/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 ---
 
-# Network Map — Inteligencia de contactos para warm intros
+# Network Map - Inteligencia de contactos para warm intros
 
 Convertís el **export de conexiones de LinkedIn** en inteligencia accionable: dado un target company, quién de tu red 1er-grado trabaja (o trabajó) ahí, quién puede darte un warm intro, y un mensaje custom por contacto. Reemplaza a LinkedIn Premium para esto: solo necesitás tu propio export + Claude.
 
@@ -20,9 +20,9 @@ En LinkedIn → **Settings → Data Privacy → Get a copy of your data → Down
 ## Qué produce
 
 Dado un target company:
-1. **1er-grado en la empresa** — contactos tuyos que trabajan ahí ahora (match por `Company`).
-2. **Paths de warm intro** — contactos 1er-grado que probablemente conozcan gente del target (ej. ex-empleados de la empresa, gente del mismo rubro/rol) y podrían presentarte. *Nota honesta:* el export solo tiene tus 1er-grado; el verdadero 2do-grado (las conexiones de ellos) no está en el archivo. Lo que hacemos es **inferir** buenos candidatos a intro desde tus 1er-grado (empleo actual/pasado en el target, overlap de empresa/rol), no leer la red de cada uno.
-3. **Mensaje por contacto** — template custom según historia compartida (misma empresa pasada, mismo rubro, conexión vieja vs reciente).
+1. **1er-grado en la empresa** - contactos tuyos que trabajan ahí ahora (match por `Company`).
+2. **Paths de warm intro** - contactos 1er-grado que probablemente conozcan gente del target (ej. ex-empleados de la empresa, gente del mismo rubro/rol) y podrían presentarte. *Nota honesta:* el export solo tiene tus 1er-grado; el verdadero 2do-grado (las conexiones de ellos) no está en el archivo. Lo que hacemos es **inferir** buenos candidatos a intro desde tus 1er-grado (empleo actual/pasado en el target, overlap de empresa/rol), no leer la red de cada uno.
+3. **Mensaje por contacto** - template custom según historia compartida (misma empresa pasada, mismo rubro, conexión vieja vs reciente).
 
 ## El motor
 
@@ -40,10 +40,10 @@ Devuelve nombre, posición, empresa, URL del perfil y fecha de conexión. Vos (C
 
 ## Modos
 
-### `import <path>` — Registrar el export
+### `import <path>` - Registrar el export
 Copiar/referenciar `Connections.csv` en `05-Contactos/`, verificar que parsea (corré el script con `--top-companies`), y reportar tamaño de la red + top empresas.
 
-### `[company]` — Mapear una empresa
+### `[company]` - Mapear una empresa
 1. Correr el script filtrando por la empresa.
 2. Clasificar: 1er-grado actuales en la empresa vs candidatos a warm-intro (ex-empleados / mismo rubro).
 3. Priorizar por relevancia (seniority/rol vs tu objetivo) y calidez (conexión reciente, historia compartida).
@@ -53,7 +53,7 @@ Copiar/referenciar `Connections.csv` en `05-Contactos/`, verificar que parsea (c
 ## Reglas
 
 - Data de terceros: tratamiento local, nunca a un remoto sin confirmación; respetá privacidad.
-- No inventar relaciones ni 2do-grado que el export no soporta — sé explícito sobre qué es dato y qué es inferencia.
+- No inventar relaciones ni 2do-grado que el export no soporta - sé explícito sobre qué es dato y qué es inferencia.
 - Calidad sobre cantidad: 5 contactos bien elegidos > 50 mensajes genéricos.
 
 ## Handoff

package/skills/order-lifecycle/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: order-lifecycle
+description: "Design the order lifecycle — order state machine, fulfillment workflow, returns/RMA, refunds, cancellations, and order events/webhooks. Platform-agnostic state and event modeling. Triggers: designing order states, modeling returns/refunds, defining order events."
+argument-hint: "[design | states | returns]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Order Lifecycle
+
+An order is a long-lived state machine touched by payments, inventory, shipping, and support. Model its states, transitions, and events explicitly so nothing silently gets stuck — independent of platform.
+
+> **Note:** This skill may create or modify files in your project (a state-machine spec). It will ask before writing.
+
+## Before Starting
+
+Gather: fulfillment model (single vs split/partial shipments), payment capture timing (auth-then-capture vs immediate), returns policy, and goal (design the full lifecycle, define the state machine, or model returns/refunds).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | End-to-end lifecycle + events |
+| **States** | `states` | Formal state machine: states, transitions, guards |
+| **Returns** | `returns` | RMA + refund flow and states |
+
+---
+
+## Phase 1 — The State Machine
+
+Separate **order status** from **payment status** and **fulfillment status** — collapsing them into one field is the most common modeling mistake.
+
+| Dimension | States |
+|-----------|--------|
+| **Order** | pending → confirmed → in_progress → completed / cancelled |
+| **Payment** | pending → authorized → paid → partially_refunded → refunded / failed |
+| **Fulfillment** | unfulfilled → partially_fulfilled → fulfilled → returned |
+
+Each transition has a **guard** (e.g. cannot fulfill before payment authorized) and emits an **event**.
+
+For the full transition table, guards, and partial-shipment handling, see [references/order-state-machine.md](references/order-state-machine.md).
+
+---
+
+## Phase 2 — Events & Webhooks
+
+Every transition emits a durable, ordered event: `order.created`, `order.paid`, `order.fulfilled`, `order.cancelled`, `order.refunded`, `return.requested`, `return.received`.
+
+- Events are **append-only** — never mutate history; the current state is a projection.
+- Outbound webhooks must be **idempotent and retried** with signatures (hand off to `payments-architecture` for the reliability pattern).
+- Carry an idempotency key from order placement through fulfillment.
+
+---
+
+## Phase 3 — Returns & Refunds
+
+Flow: `return.requested → approved → label_sent → in_transit → received → inspected → refunded/rejected`.
+
+| Concern | Rule |
+|---------|------|
+| Restock | Only on `received + inspected` pass, back to `available` |
+| Refund | Full / partial / store-credit; never exceed captured amount |
+| Window | Enforce return-window guard at request time |
+| Partial | Per line-item, not whole-order, for split fulfillment |
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Lifecycle diagram + event catalog |
+| States | State/transition/guard table (the spec) |
+| Returns | RMA flow + refund rules |
+
+A lifecycle design is **COMPLETE** when order/payment/fulfillment statuses are independent, every transition has a guard and an event, and refunds/restocks are gated on inspection.
+
+---
+
+## Related Skills
+
+- **payments-architecture**: capture/refund and webhook reliability for order events.
+- **inventory-stock**: reservations released and stock decremented per fulfillment.
+- **cart-checkout**: hands the placed order into this lifecycle.
+- **commerce-analytics**: order events feed funnel and revenue metrics.

package/skills/order-lifecycle/references/order-state-machine.md

@@ -0,0 +1,53 @@
+# Order State Machine — Transitions, Guards & Events
+
+Three independent dimensions. Keep them separate; the overall order status is a projection, not a stored mega-enum.
+
+## Order status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| (start) | pending | order placed | `order.created` |
+| pending | confirmed | payment authorized | `order.confirmed` |
+| confirmed | in_progress | fulfillment started | `order.processing` |
+| in_progress | completed | all items fulfilled | `order.completed` |
+| pending/confirmed | cancelled | not yet shipped | `order.cancelled` |
+
+## Payment status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| pending | authorized | auth succeeded | `payment.authorized` |
+| authorized | paid | captured | `payment.captured` |
+| paid | partially_refunded | refund < captured | `payment.refunded` |
+| paid | refunded | refund == captured | `payment.refunded` |
+| pending/authorized | failed | gateway decline | `payment.failed` |
+
+## Fulfillment status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| unfulfilled | partially_fulfilled | some lines shipped | `fulfillment.partial` |
+| partially_fulfilled | fulfilled | all lines shipped | `fulfillment.completed` |
+| fulfilled | returned | RMA received | `return.received` |
+
+## Cross-dimension guards (the important rules)
+- Cannot transition fulfillment past `unfulfilled` until payment is `authorized` (or `paid`, per capture policy).
+- Cannot `cancel` once any line is `fulfilled` — use returns instead.
+- Capture timing: auth at placement, capture at first fulfillment (auth/capture model) OR capture immediately (decide once).
+
+## Returns / RMA sub-flow
+`return.requested → approved → label_sent → in_transit → received → inspected → (refunded | rejected)`
+
+| Concern | Rule |
+|---------|------|
+| Window | Guard `requested` against return-window from delivery date |
+| Restock | Only on `inspected` pass → quantity back to `available` |
+| Refund | ≤ captured amount; full / partial / store-credit |
+| Partial | Per line item for split fulfillment |
+
+## Events are append-only
+Persist every event with: id, order_id, type, payload, timestamp, idempotency_key. Current state = fold over events. Outbound webhooks must be signed, deduplicated, and retried (see `payments-architecture`).
+
+## Verdict: COMPLETE when
+- [ ] Order / payment / fulfillment statuses are independent fields
+- [ ] Every transition has a guard and emits an event
+- [ ] Cancel blocked after fulfillment; returns handle post-ship
+- [ ] Restock gated on inspection; refunds capped at captured amount
+- [ ] Events are append-only with idempotency keys

package/skills/payments-architecture/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: payments-architecture
+description: "Design payment architecture independent of any single processor — gateway selection, payment intents, idempotency, webhook reliability, reconciliation, PCI scope, fraud, and refunds. Complements processor-specific skills. Triggers: choosing a PSP, designing webhook handling, reducing PCI scope, reconciling payments."
+argument-hint: "[design | webhooks | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Payments Architecture
+
+The payment layer must never double-charge, never lose a webhook, and never widen PCI scope. This skill designs the processor-agnostic architecture; processor-specific implementation (e.g. Stripe) is a handoff.
+
+## Before Starting
+
+Gather: markets/currencies, payment methods (cards, wallets, local methods), capture model (immediate vs auth/capture), subscription needs, and goal (design the architecture, harden webhooks, or audit an existing integration).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Gateway choice + payment flow + PCI strategy |
+| **Webhooks** | `webhooks` | Reliable, idempotent webhook handling design |
+| **Audit** | `audit` | Risk review of an existing integration |
+
+---
+
+## Phase 1 — Flow & Idempotency
+
+Use the **payment intent** model regardless of processor: create intent → confirm → succeeded/failed, with status mirrored onto the order.
+
+| Principle | Why |
+|-----------|-----|
+| **Idempotency keys** on every create/charge | A retried request must not double-charge |
+| **Server-authoritative amounts** | Never trust client-sent totals; re-price server-side |
+| **Auth then capture** (where supported) | Capture at fulfillment, not at order placement |
+| **Money as integer minor units** | No floats for currency, ever |
+
+---
+
+## Phase 2 — Webhook Reliability
+
+Webhooks are the source of truth for async payment outcomes — treat them as unreliable transport:
+
+1. **Verify the signature** before doing anything.
+2. **Deduplicate** by event id (idempotent processing) — providers redeliver.
+3. **Persist then process** — store the raw event, ack fast (2xx), process out of band.
+4. **Tolerate out-of-order** delivery; reconcile against current state, don't assume sequence.
+5. **Reconcile** daily against the processor's ledger to catch missed events.
+
+For the persist-ack-process pattern, retry/backoff, and reconciliation report design, apply the principles above and hand processor specifics to `stripe-integration-expert`.
+
+---
+
+## Phase 3 — PCI Scope & Fraud
+
+- **Minimize PCI scope:** use hosted fields / tokenization so raw PAN never touches your servers (SAQ A). Never log card data.
+- **Fraud:** combine processor risk signals with velocity checks, AVS/CVV, and 3-D Secure for high-risk; balance friction vs chargebacks.
+- **Refunds:** never exceed captured amount; support partial; emit `payment.refunded` to the order lifecycle.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Gateway selection + intent flow + PCI scope plan |
+| Webhooks | Idempotent handler design + reconciliation plan |
+| Audit | Findings: SECURE / CONCERNS / FAIL per area |
+
+A payment architecture is **SECURE** when charges are idempotent, amounts are server-authoritative, webhooks are signature-verified and deduplicated, money is integer minor units, and PCI scope is minimized.
+
+---
+
+## Related Skills
+
+- **stripe-integration-expert**: processor-specific implementation once this architecture is set.
+- **cart-checkout**: invokes the payment step.
+- **order-lifecycle**: consumes payment events (paid, refunded).
+- **subscription-billing**: recurring charges build on this layer.