@sadrmanesh/commerce-agent-skills 0.0.0-stage → 0.3.0

package/skills/storefront-accessibility/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: storefront-accessibility
+description: "Build product, cart, and checkout pages that meet WCAG 2.2 AA: keyboard use, visible focus, labels and autocomplete, announced errors and cart updates, contrast, and target size. Use when building or reviewing storefront UI, forms, filters, carousels, or checkout for accessibility."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Storefront accessibility
+
+A shopper who cannot reach the buy button with a keyboard, or does not hear that the cart changed, cannot buy. Aim for WCAG 2.2 level AA on every step from search to order confirmation. The success criteria that matter most in a store are listed in [the WCAG checklist](references/wcag-checklist.md).
+
+## Procedure
+
+1. Use native elements first: `<button>` for actions, `<a href>` for navigation, `<select>`, `<input type="radio">`, and `<fieldset>` with `<legend>` for option groups. Add ARIA only where no native element fits.
+2. Make every action work with a keyboard in a logical order, with a visible focus indicator that is not hidden behind sticky headers or cookie banners.
+3. Give every form field a visible `<label>` and the right `autocomplete` token (`given-name`, `postal-code`, `email`, `tel`, `cc-number`).
+4. Announce changes that happen without a page load: "Added to cart", a new cart total, filter result counts. Use a polite live region (`role="status"` or `aria-live="polite"`).
+5. On a form error, name the field and the fix in text, link the error summary to the fields, set `aria-invalid="true"`, and move focus to the summary or the first invalid field.
+6. Check color contrast: 4.5:1 for normal text, 3:1 for large text and for focus indicators, borders of inputs, and icons that carry meaning.
+7. Make touch and click targets at least 24 by 24 CSS pixels, or space them so the 24 pixel circle around each does not overlap another.
+8. Test with a keyboard only, a screen reader, 200 percent zoom, and an automated checker on the product, cart, and checkout templates.
+
+## Product pages
+
+- Variation pickers are radio groups or selects with a group label ("Size"). A color swatch has a text name, not only a color. Unavailable options say so in text.
+- Price changes after picking a variation are announced.
+- Images have `alt` text that says what differs between them ("Back view, blue"). Decorative images have `alt=""`.
+- Carousels have pause controls, do not auto-advance faster than a shopper can read, and can be used with a keyboard.
+
+## Cart and checkout
+
+- Quantity steppers are buttons with names ("Increase quantity of Blue mug"), and the input accepts typed values.
+- Do not ask for the same information twice in one flow. Offer "same as shipping" for billing (WCAG 3.3.7 Redundant Entry).
+- Do not require solving a puzzle or remembering a code to sign in or pay, unless an alternative exists (3.3.8 Accessible Authentication). Allow password managers and pasting one-time codes.
+- Session timeouts warn the shopper and let them extend, so a slow shopper does not lose the cart.
+- The order confirmation page has a clear heading and the order number as text.
+
+## Gotchas
+
+- `<div onclick>` buttons are not focusable and are not announced as buttons.
+- A placeholder is not a label. It disappears when typing starts and often fails contrast.
+- `outline: none` without a replacement focus style hides where the keyboard is.
+- Opening a mini-cart drawer without moving focus into it, or without returning focus when it closes, strands keyboard users.
+- Infinite scroll without a "load more" button hides the footer and is hard to navigate by keyboard.
+- Disabled "Place order" buttons with no explanation leave shoppers stuck. Keep it enabled and explain errors on submit.
+
+## Verification
+
+- The whole purchase, from search to confirmation, completes with a keyboard only.
+- A screen reader announces the add-to-cart result and the new cart count.
+- Submitting checkout with an empty postal code moves focus to an error that names the field.
+- Text and focus indicators meet the contrast ratios above.
+- The page is usable at 200 percent zoom and 320 CSS pixels wide without horizontal scrolling.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/storefront-accessibility/evals/examples/add-to-cart-announcement.md

@@ -0,0 +1,3 @@
+Use a real `<button>` for add to cart so it is focusable and announced as a button. After the request succeeds, write "Blue mug added to cart. Cart has 3 items." into a `role="status"` live region that already exists in the page. Update the badge text too, with a visually hidden "items in cart" label.
+
+Leave focus on the button after adding. If the mini-cart drawer opens, move focus into it, trap focus while it is open, and return focus to the button when it closes.

package/skills/storefront-accessibility/evals/examples/checkout-errors.md

@@ -0,0 +1,3 @@
+Give every field a visible `<label>` and keep the placeholder only for an example value. Add `autocomplete` tokens such as `given-name`, `address-line1`, `postal-code`, `email`, and `tel`.
+
+On submit, show an error summary with links to each invalid field, write each error in text next to the field, set `aria-invalid="true"`, and move focus to the summary. A red border alone fails for color-blind shoppers, so add an icon and text, and check the border and text contrast against the background.

package/skills/storefront-accessibility/evals/tasks.json

@@ -0,0 +1,20 @@
+{
+  "tasks": [
+    {
+      "id": "add-to-cart-announcement",
+      "task": "The add-to-cart button updates a mini-cart badge with JavaScript. Make the result accessible to screen reader and keyboard users.",
+      "expects": {
+        "must_include": ["<button>", "role=\"status\"", "focus"],
+        "must_not_include": ["<div onclick"]
+      }
+    },
+    {
+      "id": "checkout-errors",
+      "task": "Review a checkout form whose fields use placeholders as labels and show errors only as red borders. List the fixes.",
+      "expects": {
+        "must_include": ["<label>", "autocomplete", "aria-invalid", "contrast"],
+        "must_not_include": ["placeholder is enough"]
+      }
+    }
+  ]
+}

package/skills/storefront-accessibility/references/wcag-checklist.md

@@ -0,0 +1,41 @@
+# WCAG 2.2 checklist for stores
+
+Level A and AA success criteria that storefronts most often fail. Numbers refer to WCAG 2.2.
+
+| Criterion | Level | In a store |
+| --- | --- | --- |
+| 1.1.1 Non-text Content | A | Product image `alt`, icon buttons with names, swatches with text |
+| 1.3.1 Info and Relationships | A | Headings, lists, tables for size charts, `fieldset` and `legend` for options |
+| 1.3.5 Identify Input Purpose | AA | `autocomplete` on address, email, phone, and payment fields |
+| 1.4.3 Contrast (Minimum) | AA | 4.5:1 text, 3:1 large text, including sale prices and badges |
+| 1.4.10 Reflow | AA | Usable at 320 CSS pixels wide |
+| 1.4.11 Non-text Contrast | AA | 3:1 for input borders, focus rings, and meaningful icons |
+| 2.1.1 Keyboard | A | Filters, swatches, carousels, mini-cart, and payment fields |
+| 2.2.1 Timing Adjustable | A | Cart or checkout timeouts can be extended |
+| 2.2.2 Pause, Stop, Hide | A | Auto-advancing carousels and countdown banners |
+| 2.4.3 Focus Order | A | Drawers and modals trap and return focus |
+| 2.4.7 Focus Visible | AA | A visible focus style everywhere |
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Sticky headers and cookie banners do not cover focus |
+| 2.5.8 Target Size (Minimum) | AA | 24 by 24 CSS pixels, or enough spacing |
+| 3.3.1 Error Identification | A | Errors in text, naming the field |
+| 3.3.3 Error Suggestion | AA | Say how to fix it: "Enter a 5-digit postal code" |
+| 3.3.7 Redundant Entry | A | "Same as shipping" for billing |
+| 3.3.8 Accessible Authentication (Minimum) | AA | No puzzle or memory test to sign in. Allow paste and password managers. |
+| 4.1.2 Name, Role, Value | A | Custom controls expose role and state, such as `aria-expanded` and `aria-pressed` |
+| 4.1.3 Status Messages | AA | Cart updates and result counts in a live region |
+
+## Live region pattern
+
+```html
+<div role="status" class="visually-hidden" id="cart-status"></div>
+<script>
+  function announceCart(message) {
+    const region = document.getElementById("cart-status");
+    region.textContent = "";
+    requestAnimationFrame(() => { region.textContent = message; });
+  }
+  // announceCart("Blue mug added to cart. Cart has 3 items.");
+</script>
+```
+
+The region must exist in the page before the message is written, or some screen readers miss it.

package/skills/storefront-performance/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: storefront-performance
+description: "Improve storefront Core Web Vitals (LCP, INP, CLS) using field data at the 75th percentile, image and font loading, caching of catalog pages, and lighter third-party scripts. Use when product or category pages feel slow, Web Vitals fail, or a theme, app, or script change needs a performance check."
+license: MIT
+compatibility: "The Web Vitals checker needs Node.js 20 or newer and no packages."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Storefront performance
+
+Judge speed by what real shoppers get, not one lab run. Core Web Vitals are measured at the 75th percentile of page loads, split by mobile and desktop. Thresholds and causes are in [the Web Vitals notes](references/web-vitals.md).
+
+| Metric | Good | Poor |
+| --- | --- | --- |
+| LCP, Largest Contentful Paint | 2500 ms or less | over 4000 ms |
+| INP, Interaction to Next Paint | 200 ms or less | over 500 ms |
+| CLS, Cumulative Layout Shift | 0.1 or less | over 0.25 |
+
+INP replaced First Input Delay as a Core Web Vital in March 2024.
+
+## Procedure
+
+1. Get field data per template (home, category, product, cart, checkout) from the Chrome UX Report, Search Console, or your own real-user monitoring with the `web-vitals` library. Lab tools explain causes but do not decide pass or fail.
+2. Classify the p75 values: `node scripts/check-web-vitals.mjs vitals.json` prints good, needs improvement, or poor for each template.
+3. Fix the worst metric on the highest-traffic template first.
+4. LCP: the LCP element on a product page is usually the main product image. Serve it in a modern format at the displayed size, do not lazy-load it, give it `fetchpriority="high"`, and cut server response time with full-page caching for anonymous shoppers.
+5. INP: break up long JavaScript tasks, defer third-party tags, and make variation pickers and add-to-cart update the UI before network work finishes.
+6. CLS: set `width` and `height` (or `aspect-ratio`) on images, reserve space for banners, reviews widgets, and price blocks, and avoid inserting content above what the shopper is reading.
+7. Recheck field data after 28 days, the window the Chrome UX Report uses.
+
+## Caching a store
+
+Cache category and product pages for shoppers without a session. Bypass the cache for cart, checkout, account pages, and requests carrying cart or session cookies. Load the mini-cart count with a small request instead of disabling the page cache. Purge a product's page when its price or stock changes.
+
+## Third-party scripts
+
+Chat widgets, review apps, A/B testing, and tag managers often cost more than the theme. List every script with its owner and purpose, remove unused ones, and load the rest after the page is interactive. A/B testing scripts that hide the page while loading hurt LCP directly.
+
+## Gotchas
+
+- `loading="lazy"` on the main product image delays LCP.
+- A cookie banner or promo bar inserted at the top shifts the whole page and adds CLS.
+- Web fonts without `font-display: swap` or a matching fallback can hide text or shift it.
+- Caching pages for logged-in shoppers can show one shopper's cart to another.
+- A good Lighthouse score on a desktop connection says little about mobile p75 field data.
+- Large carousels that load every slide image at once compete with the LCP image.
+
+## Verification
+
+- Every template's p75 LCP, INP, and CLS is classified, mobile and desktop separately.
+- The LCP image is not lazy-loaded and is requested early.
+- Cart and checkout are never served from a shared page cache.
+- After changes, field data at p75 improves over the next 28 days without a drop in conversion.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/storefront-performance/evals/examples/cache-without-leaking-carts.md

@@ -0,0 +1,3 @@
+Cache product, category, and home pages only for shoppers without a session, and bypass the cache for cart, checkout, and my-account pages, and for any request carrying the `woocommerce_items_in_cart`, `woocommerce_cart_hash`, or `wp_woocommerce_session_` cookie, or a logged-in cookie.
+
+Load the mini-cart count with a small uncached request after the page loads, so cached HTML never holds a shopper's cart. Purge a product's page when its price or stock changes.

package/skills/storefront-performance/evals/examples/slow-product-lcp.md

@@ -0,0 +1,3 @@
+At the 75th percentile, 4.6 seconds is poor (above 4000 ms); the target is 2500 ms or less. The LCP element is the main product image, so remove lazy loading from it, add `fetchpriority="high"`, and serve an AVIF or WebP at the displayed size with `srcset`.
+
+Move the review widget below the product details, reserve its height so it does not shift the page, and load its script after the page is interactive. Check Time to First Byte too, and cache the product page for anonymous shoppers. Recheck the field data after 28 days.

package/skills/storefront-performance/evals/tasks.json

@@ -0,0 +1,20 @@
+{
+  "tasks": [
+    {
+      "id": "slow-product-lcp",
+      "task": "Mobile field data shows a p75 LCP of 4.6 seconds on product pages. The main image is lazy-loaded and a review widget loads at the top. What do you do?",
+      "expects": {
+        "must_include": ["75th percentile", "LCP", "fetchpriority", "2500"],
+        "must_not_include": ["loading=\"lazy\" on the main"]
+      }
+    },
+    {
+      "id": "cache-without-leaking-carts",
+      "task": "Add full-page caching to a WooCommerce store without showing one shopper's cart to another.",
+      "expects": {
+        "must_include": ["cart", "checkout", "cookie", "bypass"],
+        "must_not_include": ["cache every page for everyone"]
+      }
+    }
+  ]
+}

package/skills/storefront-performance/references/web-vitals.md

@@ -0,0 +1,55 @@
+# Web Vitals notes
+
+## Thresholds
+
+| Metric | Good | Needs improvement | Poor |
+| --- | --- | --- | --- |
+| LCP | at most 2500 ms | 2500 to 4000 ms | above 4000 ms |
+| INP | at most 200 ms | 200 to 500 ms | above 500 ms |
+| CLS | at most 0.1 | 0.1 to 0.25 | above 0.25 |
+
+A page passes when all three are good at the 75th percentile.
+
+## LCP parts
+
+LCP time splits into four parts. Find the biggest one first.
+
+1. Time to First Byte: server, cache misses, redirects.
+2. Resource load delay: the image is discovered late, for example set by JavaScript or CSS.
+3. Resource load duration: the file is too big.
+4. Element render delay: render-blocking CSS or scripts, or a hidden page from an A/B testing script.
+
+Preload the LCP image when it is not in the initial HTML:
+
+```html
+<link rel="preload" as="image" href="/img/mug-800.avif" imagesrcset="/img/mug-400.avif 400w, /img/mug-800.avif 800w" imagesizes="(max-width: 600px) 100vw, 50vw" fetchpriority="high">
+```
+
+## Collecting field data
+
+```js
+import { onLCP, onINP, onCLS } from "web-vitals";
+
+function send(metric) {
+  navigator.sendBeacon("/vitals", JSON.stringify({
+    name: metric.name,
+    value: metric.value,
+    rating: metric.rating,
+    template: document.body.dataset.template,
+  }));
+}
+
+onLCP(send);
+onINP(send);
+onCLS(send);
+```
+
+Group the values by template and device, then take the 75th percentile.
+
+## Input file for the checker
+
+```json
+[
+  { "template": "product", "device": "mobile", "lcp": 3100, "inp": 180, "cls": 0.02 }
+]
+```

package/skills/storefront-performance/scripts/check-web-vitals.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Classify p75 Core Web Vitals per template.
+// Usage: node check-web-vitals.mjs <vitals.json>
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const THRESHOLDS = {
+  lcp: { good: 2500, poor: 4000 },
+  inp: { good: 200, poor: 500 },
+  cls: { good: 0.1, poor: 0.25 },
+};
+
+/** Rates one value as "good", "needs-improvement", or "poor". */
+export function rate(metric, value) {
+  const threshold = THRESHOLDS[metric];
+  if (!threshold) throw new Error(`unknown metric ${metric}`);
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${metric} must be a number of 0 or more`);
+  if (value <= threshold.good) return "good";
+  if (value <= threshold.poor) return "needs-improvement";
+  return "poor";
+}
+
+/** Rates each row and says whether it passes (all three metrics good). */
+export function checkWebVitals(rows) {
+  return rows.map((row) => {
+    const ratings = {};
+    for (const metric of Object.keys(THRESHOLDS)) {
+      ratings[metric] = row[metric] === undefined ? "missing" : rate(metric, row[metric]);
+    }
+    const passes = Object.values(ratings).every((rating) => rating === "good");
+    return { template: row.template, device: row.device ?? "all", ratings, passes };
+  });
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+  const [file] = process.argv.slice(2);
+  if (!file) {
+    console.error("Usage: node check-web-vitals.mjs <vitals.json>");
+    process.exit(2);
+  }
+  const results = checkWebVitals(JSON.parse(await readFile(file, "utf8")));
+  for (const result of results) {
+    const parts = Object.entries(result.ratings).map(([metric, rating]) => `${metric.toUpperCase()} ${rating}`);
+    console.log(`${result.passes ? "pass" : "fail"}  ${result.template} (${result.device}): ${parts.join(", ")}`);
+  }
+  process.exit(results.every((result) => result.passes) ? 0 : 1);
+}

package/skills/stripe-payments/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: stripe-payments
+description: "Take card and wallet payments with Stripe PaymentIntents or Checkout Sessions, idempotency keys, and signed webhooks that move the order to paid. Use when adding Stripe to a store, handling Stripe webhooks, or refunding through the Stripe API."
+license: MIT
+compatibility: "The signature checker needs Node.js 20 or newer and no packages."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Stripe payments
+
+This skill applies the general rules in the payment gateway skill to Stripe. Event names, objects, and status values are in [the Stripe objects notes](references/stripe-objects.md).
+
+## Procedure
+
+1. Pick one integration per checkout. A **Checkout Session** is a Stripe-hosted page. A **PaymentIntent** with the Payment Element keeps the shopper on your page. Both keep card data on Stripe.
+2. Create the shop order first, unpaid. Then create the PaymentIntent or Checkout Session on the server with the amount from the order, never from the browser.
+3. Put the shop order id in `metadata` (`metadata[order_id]`) and send an `Idempotency-Key` header derived from the order and attempt, such as `order-1042-attempt-1`.
+4. Return only the `client_secret` (PaymentIntent) or the session `url` (Checkout) to the browser. The secret key `sk_...` stays on the server.
+5. Mark the order paid from a verified webhook: `payment_intent.succeeded` for PaymentIntents, or `checkout.session.completed` with `payment_status` equal to `paid` for Checkout.
+6. Pin the API version for the account and the webhook endpoint, so a dashboard upgrade does not change payloads under you.
+
+## Amounts
+
+Stripe amounts are integers in the currency's smallest unit: `1999` is 19.99 USD. Zero-decimal currencies such as JPY are sent as the whole amount: `500` is 500 JPY. Compute the integer from the order total with the currency's exponent and compare the webhook's `amount_received` and `currency` with the order before marking it paid.
+
+## Webhooks
+
+- Read the raw body. A JSON parser that reformats the body breaks the signature.
+- Verify the `Stripe-Signature` header with the endpoint secret `whsec_...`. The header has a timestamp `t` and one or more `v1` signatures. The signed payload is `t`, a dot, and the raw body, hashed with HMAC-SHA256 and hex encoded. Reject timestamps older than the tolerance, 300 seconds by default.
+- Run `node scripts/verify-stripe-signature.mjs <body-file> "<Stripe-Signature header>"` with `STRIPE_WEBHOOK_SECRET` set to check a captured delivery.
+- Store `event.id` in a table with a unique constraint before acting. Stripe can send the same event more than once, and out of order.
+- Return `2xx` quickly after storing the event, then do slow work in a job.
+- For events where order matters, retrieve the object (`GET /v1/payment_intents/{id}`) and act on its current status instead of the event's snapshot.
+
+## Status
+
+| PaymentIntent `status` | Shop effect |
+| --- | --- |
+| `requires_payment_method` | Unpaid. After a decline, the shopper can try again with the same intent. |
+| `requires_action` | Unpaid. The shopper must finish 3-D Secure or a redirect. |
+| `processing` | On hold. Bank debits and some wallets settle later. |
+| `requires_capture` | Authorized only. Capture before the authorization expires, or release it. |
+| `succeeded` | Paid. Store the latest charge id. |
+| `canceled` | Cancel the order only if it is still unpaid. |
+
+## Refunds and disputes
+
+- Refund with `POST /v1/refunds` and `payment_intent`, plus `amount` for a partial refund. Send an idempotency key per refund attempt and store the refund id.
+- A refund can stay `pending` and can later fail. Update the shop refund from `refund.updated` or `charge.refund.updated`, not from the create response alone.
+- `charge.dispute.created` opens a dispute. Flag the order and collect evidence. Do not refund automatically, because a refund does not close a dispute.
+
+## Gotchas
+
+- Creating a new PaymentIntent on every checkout page load leaves many incomplete intents and can charge twice if two are confirmed. Reuse the intent stored on the order.
+- Marking the order paid on the `return_url` page is wrong. The redirect arrives before, after, or without the webhook.
+- Test-mode and live-mode keys, webhook secrets, and object ids are separate. A live event never verifies with the test secret.
+- A `v1` signature compare with `==` leaks timing. Use a constant-time compare.
+- Idempotency keys are kept for at least 24 hours. Reusing a key with different parameters returns an error, not a new payment.
+
+## Verification
+
+- A forged webhook, or a real one older than five minutes, is rejected with `400`.
+- Delivering the same `payment_intent.succeeded` event twice sends one receipt and reduces stock once.
+- A `payment_intent.succeeded` whose `amount_received` differs from the order total leaves the order unpaid and flags it.
+- A Checkout Session with `payment_status` `unpaid` (a delayed bank method) does not mark the order paid until `checkout.session.async_payment_succeeded`.
+- A partial refund through `POST /v1/refunds` leaves the order paid for the remainder.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/stripe-payments/evals/examples/checkout-session-delayed.md

@@ -0,0 +1,3 @@
+On `checkout.session.completed`, read `payment_status`. For a bank debit it is `unpaid`, so record the PaymentIntent id and leave the order on hold without fulfilling it.
+
+When `checkout.session.async_payment_succeeded` arrives, verify it, check the amount, and mark the order paid. If `checkout.session.async_payment_failed` arrives instead, mark the order failed and email the shopper a link to pay again.

package/skills/stripe-payments/evals/examples/mark-paid-from-webhook.md

@@ -0,0 +1,5 @@
+Create the PaymentIntent on the server from the order total with `metadata[order_id]` and an `Idempotency-Key` per attempt.
+
+The order becomes paid only in the webhook handler. Verify the `Stripe-Signature` header against the raw body with the endpoint secret, then insert `event.id` into a table with a unique constraint. If the insert conflicts, return `200` and stop, because the event was already handled.
+
+For `payment_intent.succeeded`, load the order from `metadata.order_id`, compare `amount_received` and `currency` with the order total in minor units, and mark it paid once. The browser redirect only shows a pending page until the order record says paid.

package/skills/stripe-payments/evals/examples/partial-refund.md

@@ -0,0 +1,3 @@
+Call `POST /v1/refunds` with `payment_intent=pi_123` and `amount=500`, because Stripe amounts are integers in cents. Send `Idempotency-Key: refund-1042-1` so a retried request does not refund twice.
+
+Create the shop refund record as pending with the returned `re_` id. Update it to succeeded or failed from `refund.updated`. The order stays paid for the remaining 14.99 USD.

package/skills/stripe-payments/evals/tasks.json

@@ -0,0 +1,27 @@
+{
+  "tasks": [
+    {
+      "id": "mark-paid-from-webhook",
+      "task": "A store creates a Stripe PaymentIntent at checkout. Explain how and when the order should become paid, including how to handle a duplicate delivery.",
+      "expects": {
+        "must_include": ["payment_intent.succeeded", "Stripe-Signature", "event.id", "amount_received"],
+        "must_not_include": ["return_url marks the order paid"]
+      }
+    },
+    {
+      "id": "partial-refund",
+      "task": "Refund 5.00 USD of a 19.99 USD Stripe payment from the shop admin and keep the shop record in sync when the refund settles.",
+      "expects": {
+        "must_include": ["POST /v1/refunds", "500", "Idempotency-Key", "refund.updated"],
+        "must_not_include": ["amount=5.00"]
+      }
+    },
+    {
+      "id": "checkout-session-delayed",
+      "task": "A Stripe Checkout Session completes with a bank debit that settles days later. Say what the webhook handler does now and later.",
+      "expects": {
+        "must_include": ["checkout.session.completed", "payment_status", "checkout.session.async_payment_succeeded"]
+      }
+    }
+  ]
+}

package/skills/stripe-payments/references/stripe-objects.md

@@ -0,0 +1,54 @@
+# Stripe objects and events
+
+## Objects
+
+| Object | Id prefix | Use |
+| --- | --- | --- |
+| PaymentIntent | `pi_` | One payment attempt cycle for one order. Holds `amount`, `currency`, `status`, `metadata`, and `latest_charge`. |
+| Checkout Session | `cs_` | A hosted payment page. Has `payment_status` (`paid`, `unpaid`, `no_payment_required`) and a `payment_intent`. |
+| Charge | `ch_` | The movement of money behind a PaymentIntent. Refunds and disputes point at it. |
+| Refund | `re_` | A full or partial refund. `status` is `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. |
+| Dispute | `dp_` | A chargeback. Respond with evidence before `evidence_details.due_by`. |
+| Event | `evt_` | A webhook delivery body. `id` is stable across retries, so use it for deduplication. |
+
+## Events a store usually handles
+
+| Event | Action |
+| --- | --- |
+| `payment_intent.succeeded` | Mark paid after checking amount and currency |
+| `payment_intent.payment_failed` | Record the decline. Keep the order unpaid. |
+| `payment_intent.canceled` | Cancel the order if still unpaid |
+| `checkout.session.completed` | Mark paid if `payment_status` is `paid`. Otherwise wait. |
+| `checkout.session.async_payment_succeeded` | Mark paid for a delayed method |
+| `checkout.session.async_payment_failed` | Mark failed for a delayed method |
+| `charge.refunded` | Reconcile refunds made outside the shop admin |
+| `refund.updated` | Update a pending refund to succeeded or failed |
+| `charge.dispute.created` | Flag the order and start the evidence task |
+
+Subscribe the endpoint only to the events you handle. Every other event still has to return `2xx` if it arrives.
+
+## Signature header
+
+```text
+Stripe-Signature: t=1730300000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
+```
+
+Compute `HMAC-SHA256(secret, "1730300000." + rawBody)` as lowercase hex and compare it with each `v1` value. During secret rotation the header can carry two `v1` values. Ignore `v0`.
+
+## Requests
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "$STRIPE_SECRET_KEY:" \
+  -H "Idempotency-Key: order-1042-attempt-1" \
+  -d amount=1999 -d currency=usd \
+  -d "automatic_payment_methods[enabled]=true" \
+  -d "metadata[order_id]=1042"
+```
+
+```bash
+curl https://api.stripe.com/v1/refunds \
+  -u "$STRIPE_SECRET_KEY:" \
+  -H "Idempotency-Key: refund-1042-1" \
+  -d payment_intent=pi_123 -d amount=500
+```

package/skills/stripe-payments/scripts/verify-stripe-signature.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Verify a Stripe-Signature header against a raw webhook body.
+// Usage: STRIPE_WEBHOOK_SECRET=whsec_... node verify-stripe-signature.mjs <body-file> "<header>" [--now <unix seconds>]
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+
+export function parseStripeSignature(header) {
+  const result = { timestamp: null, signatures: [] };
+  for (const part of String(header ?? "").split(",")) {
+    const index = part.indexOf("=");
+    if (index === -1) continue;
+    const key = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (key === "t" && /^\d+$/.test(value)) result.timestamp = Number(value);
+    if (key === "v1" && /^[0-9a-f]{64}$/.test(value)) result.signatures.push(value);
+  }
+  return result;
+}
+
+export function signStripePayload(rawBody, secret, timestamp) {
+  return createHmac("sha256", secret).update(`${timestamp}.${rawBody}`, "utf8").digest("hex");
+}
+
+/** Returns a list of problems. An empty list means the delivery is authentic and fresh. */
+export function verifyStripeSignature(rawBody, header, secret, { now = Math.floor(Date.now() / 1000), tolerance = DEFAULT_TOLERANCE_SECONDS } = {}) {
+  if (typeof secret !== "string" || secret === "") return ["no webhook secret"];
+  const { timestamp, signatures } = parseStripeSignature(header);
+  const errors = [];
+  if (timestamp === null) errors.push("missing t timestamp");
+  if (signatures.length === 0) errors.push("missing v1 signature");
+  if (errors.length > 0) return errors;
+  if (Math.abs(now - timestamp) > tolerance) errors.push(`timestamp outside the ${tolerance} second tolerance`);
+  const expected = Buffer.from(signStripePayload(rawBody, secret, timestamp), "hex");
+  const matched = signatures.some((signature) => {
+    const received = Buffer.from(signature, "hex");
+    return received.length === expected.length && timingSafeEqual(received, expected);
+  });
+  if (!matched) errors.push("no v1 signature matches the body");
+  return errors;
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+  const [file, header] = process.argv.slice(2);
+  const nowIndex = process.argv.indexOf("--now");
+  if (!file || !header) {
+    console.error('Usage: STRIPE_WEBHOOK_SECRET=whsec_... node verify-stripe-signature.mjs <body-file> "<header>" [--now <seconds>]');
+    process.exit(2);
+  }
+  const body = await readFile(file, "utf8");
+  const options = nowIndex === -1 ? {} : { now: Number(process.argv[nowIndex + 1]) };
+  const errors = verifyStripeSignature(body, header, process.env.STRIPE_WEBHOOK_SECRET, options);
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  console.log("Signature valid.");
+}

package/skills/subscription-billing/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: subscription-billing
+description: "Model subscription state, renewal charges, proration, and dunning without treating a renewal as a new one-time checkout. Use when adding or changing recurring billing, plan changes, cancellation, or failed renewal recovery."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Subscription billing
+
+Use this skill for recurring charges. The first payment still follows the payment skill. A renewal is another charge with its own idempotency key, not a replay of the checkout.
+
+WooCommerce core does not include subscriptions. WooCommerce Subscriptions is a separate extension. Shopify subscriptions use selling plans. Use the product the store already runs. Do not invent a cron job that inserts orders with `wp_insert_post`.
+
+## Procedure
+
+1. Store the contract separately from any one invoice: customer, plan, quantity, currency, interval, current period start and end, and status.
+2. Charge the initial invoice with the payment skill. Move the contract to `active` or `trialing` only after that payment is confirmed, unless the plan really has a trial with no charge.
+3. When a period ends, create one renewal invoice and one charge. The idempotency key is the subscription id plus the period start.
+4. On success, advance the period. On failure, follow the dunning schedule. Do not delete the entitlement on the first failure.
+5. Cancel either at period end or immediately, and record which one the shopper chose. Prorate only when the plan change says to.
+
+State transitions are in [the state notes](references/states.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Status
+
+Use these statuses unless the platform already has its own set. Map the platform's names onto them in one function.
+
+| Status | Meaning |
+| --- | --- |
+| `trialing` | Access is on. No charge yet, and a trial end is stored. |
+| `active` | The latest renewal succeeded and the period end is in the future. |
+| `past_due` | A renewal failed and retries remain. Access policy is explicit. |
+| `paused` | The merchant or shopper paused billing. No renewal is attempted. |
+| `canceled` | No further renewals. Access ends now or at the stored period end. |
+
+Do not overload `active` to mean "card on file but the last charge failed".
+
+## Renewals
+
+- One renewal invoice per period. A retried charge uses the same idempotency key.
+- The amount is the plan price at renewal time, plus tax from the tax skill, unless a scheduled price change says otherwise.
+- Store the provider payment id on that invoice. A second webhook does not create a second invoice.
+- Advance `current_period_end` only after the charge is confirmed.
+
+## Changes and cancellation
+
+- Upgrade or downgrade mid-period either waits until period end or prorates. Record the policy on the plan. Do not do both.
+- Proration is a signed amount on an invoice: unused time credited, new time debited. It is not a silent edit of a paid invoice.
+- Cancel at period end sets `cancel_at_period_end`. The status stays `active` until the period ends, then becomes `canceled`.
+- Immediate cancel stops renewal and sets the entitlement end to now. Refund the unused time only if the policy says so, through the payment skill's refund path.
+
+## Dunning
+
+- Retry a failed renewal on a short written schedule, for example day 1, day 3, and day 7. Those days are a default to configure, not a measured optimum.
+- After the last retry fails, set `canceled` or leave `past_due` with access off, according to the plan. Tell the shopper which one happened.
+- A shopper who updates the payment method retries the open invoice. It does not open a second period.
+
+## Gotchas
+
+- Treating the webhook for the first payment as every renewal will extend the period on a retry.
+- Billing today and also billing at period end double-charges the first cycle.
+- Local midnight is not a period boundary. Store period ends in UTC.
+- A paused subscription that still runs the renewal job will charge a shopper who asked to stop.
+
+## Verification
+
+- Two workers processing the same period create one invoice and one charge.
+- A failed renewal does not advance `current_period_end`.
+- Cancel at period end leaves access on until that timestamp and does not create another invoice.
+- A plan change records proration as its own invoice lines.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).