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

package/skills/subscription-billing/evals/examples/cancel-at-period-end.md

@@ -0,0 +1,3 @@
+Set `cancel_at_period_end` and leave the status `active` until the stored period end.
+
+At that timestamp the contract becomes canceled and no further renewal invoice is created.

package/skills/subscription-billing/evals/examples/one-renewal.md

@@ -0,0 +1,3 @@
+Key the renewal by the subscription id and the period start.
+
+Reuse that idempotency key for retries. Advance `current_period_end` only after the provider confirms the charge.

package/skills/subscription-billing/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "one-renewal",
+      "task": "Create a single renewal charge for a subscription period and retry it without opening a second period.",
+      "expects": {
+        "must_include": [
+          "idempotency",
+          "current_period_end"
+        ],
+        "must_not_include": [
+          "wp_insert_post"
+        ]
+      }
+    },
+    {
+      "id": "cancel-at-period-end",
+      "task": "Let a shopper cancel at period end without removing access before the period they already paid for.",
+      "expects": {
+        "must_include": [
+          "cancel_at_period_end",
+          "active"
+        ],
+        "must_not_include": [
+          "status = canceled immediately"
+        ]
+      }
+    }
+  ]
+}

package/skills/subscription-billing/references/states.md

@@ -0,0 +1,27 @@
+# Subscription states
+
+## Allowed transitions
+
+| From | Event | To |
+| --- | --- | --- |
+| `trialing` | Trial converts and the first charge succeeds | `active` |
+| `trialing` | Shopper cancels during the trial | `canceled` |
+| `active` | Renewal charge succeeds | `active` with the next period |
+| `active` | Renewal charge fails | `past_due` |
+| `active` | Cancel at period end | `active` with `cancel_at_period_end` |
+| `active` plus `cancel_at_period_end` | Period end | `canceled` |
+| `past_due` | Retry or updated payment method succeeds | `active` |
+| `past_due` | Retry schedule exhausted | `canceled` or access-off, as configured |
+| `active` or `past_due` | Pause | `paused` |
+| `paused` | Resume | `active` only after a successful charge if a period was missed |
+
+No other transition should be reachable from a client request. Unknown provider statuses do not move the contract. Store the raw provider status beside your mapped status so a person can reconcile it.
+
+## Platform mapping
+
+- Shopify: selling plans and subscription contracts are the native model. Follow the subscription APIs for the app's configured version. Do not store the contract only as a metafield you update from the browser.
+- WooCommerce Subscriptions: it is not WooCommerce core. Renewal orders and payment completion belong to that extension. Do not create renewal orders with `wp_insert_post` or `update_post_meta`. If you are on HPOS, use the extension's order APIs the same way the WooCommerce plugin skill requires for any other order.
+
+## Idempotency key
+
+`sub_{subscriptionId}_period_{periodStartIso}`. Reuse it for every retry of that period. A plan change that creates a proration invoice uses a different key that includes the change id.

package/skills/tax-and-shipping/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tax-and-shipping
+description: "Calculate tax and shipping from the destination and the store's configured rules, and store the breakdown on the order. Use when changing tax classes, shipping zones, rates, or the amount shown before payment."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Tax and shipping
+
+Use this skill when an order needs a tax or shipping amount. Checkout display is the checkout skill. Payment capture uses the total this skill produced. Do not invent a tax rate. A rate comes from the store's configuration or from a tax service the store has enabled.
+
+## Procedure
+
+1. Decide the tax address from the store's tax setting: destination, shop base, or the service's rule. Do not assume every country taxes the shipping address.
+2. Resolve each line to a tax class. Shipping may be taxed separately from goods.
+3. Calculate tax in integer minor units. Store each tax line: name or rate id, rate, and amount. Record whether prices are entered inclusive of tax.
+4. Resolve shipping from the destination to a zone, then to the methods the shopper can choose. Quote those rates before payment.
+5. Recalculate when the address, the line items, or the selected method changes. The total you charge is the last server calculation, not the first estimate.
+
+WooCommerce mapping is in [the WooCommerce notes](references/woocommerce.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Tax
+
+- A missing rate is an error or a zero-rated class the merchant configured. It is not a silent 0% you made up.
+- Inclusive and exclusive prices do not mix on one order. If the catalog is inclusive, the line price already contains tax and the tax line is the included portion.
+- Discounts reduce the taxable base according to the store's setting (before tax or after). Apply that setting once.
+- Digital and physical lines can have different classes. Do not put one rate on the order header and ignore the lines.
+- Keep the rate id that was used. A later change to the rate table must not rewrite historical orders.
+
+## Shipping
+
+- Zones are matched from the most specific address you have. Quoting a domestic rate before the country is known is an estimate and must be replaced.
+- A free method is a configured rate of zero. An address with no zone is not free shipping. Show that you cannot ship there.
+- The selected method's id and the quoted amount are stored on the order. Changing the label later does not change the amount already charged.
+- Multi-vendor shipments use one rate per merchant policy. The payout skill records who receives the shipping amount. This skill only calculates what the shopper pays.
+
+## Presentation
+
+- Show shipping, tax, and the grand total before the pay control.
+- A second currency is a display conversion. The tax and shipping amounts you persist use the order currency.
+- Round each tax line with the currency's minor units, then sum. Do not sum binary floats and round once at the end if the platform's tax API already defines the rounding.
+
+## Gotchas
+
+- Calculating tax only in the browser lets a modified client submit a lower total. Recalculate on the server.
+- Caching a shipping quote without the address, the items, and the method id will reuse another shopper's rate.
+- Tax-exempt customers need an explicit exemption on the customer or the order. Skipping tax because a field was blank marks everyone exempt.
+- Refunds refund tax in proportion to the refunded lines, using the tax that was stored, not today's rate table.
+
+## Verification
+
+- Two addresses in different zones produce the rates configured for those zones, including a zone that does not ship.
+- An order stores tax lines that add up to the tax total, in the order currency.
+- Changing the address on checkout updates the quoted shipping and tax before payment.
+- A historical order keeps its original tax amounts after you edit the live rate table.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/tax-and-shipping/evals/examples/store-tax-lines.md

@@ -0,0 +1,3 @@
+Store each tax line with its rate id and the amount in minor units.
+
+Historical orders read those stored amounts. They do not call the live rate table again.

package/skills/tax-and-shipping/evals/examples/unknown-zone.md

@@ -0,0 +1,3 @@
+Resolve the zone from the destination country and region.
+
+If no zone matches, tell the shopper you cannot ship there. A free method is only a rate the merchant configured.

package/skills/tax-and-shipping/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "store-tax-lines",
+      "task": "Persist the tax calculated for an order so a later rate-table edit does not change that order.",
+      "expects": {
+        "must_include": [
+          "rate id",
+          "minor"
+        ],
+        "must_not_include": [
+          "hard-coded 20%"
+        ]
+      }
+    },
+    {
+      "id": "unknown-zone",
+      "task": "Quote shipping only from the destination zone and refuse to invent a free rate when no zone matches.",
+      "expects": {
+        "must_include": [
+          "destination",
+          "no zone"
+        ],
+        "must_not_include": [
+          "cost of 0"
+        ]
+      }
+    }
+  ]
+}

package/skills/tax-and-shipping/references/woocommerce.md

@@ -0,0 +1,22 @@
+# WooCommerce tax and shipping
+
+Use WooCommerce's tax and shipping services. Do not reimplement a rate table in the theme.
+
+## Tax
+
+- Prices inclusive or exclusive are a store setting (`woocommerce_prices_include_tax`). Read it. Do not hard-code one mode in a plugin.
+- Tax classes live on the product. Shipping tax class is its own setting.
+- `WC_Tax::calc_tax()` and `WC_Tax::calc_shipping_tax()` take the store's rates. Pass amounts the way those methods document for the installed version, and keep minor-unit rounding consistent with `wc_get_price_decimals()`.
+- Order item tax is stored on the line (`total_tax`, `subtotal_tax`, and the rate id maps). Read it back from the order item. Do not recompute history from the current rates.
+- Checkout recalculates totals through `WC_Cart::calculate_totals()`. A custom fee or price change belongs in `woocommerce_before_calculate_totals` or a fee hook so tax runs after it.
+
+## Shipping
+
+- Zones, locations, and method instances are configured in WooCommerce. A method extends `WC_Shipping_Method` and implements `calculate_shipping( $package )`.
+- `calculate_shipping` adds rates with `add_rate()`. The `cost` is a decimal string in the store currency. A cost of `0` is a free rate you intend to offer.
+- The package destination is in `$package['destination']`. If the country is empty, do not add a domestic rate as if it were final.
+- The chosen rate is stored on the shipping order item (`method_id`, `instance_id`, `total`). HPOS does not change that. Use the order item API.
+
+## Display
+
+`wc_price()` formats amounts. Tax labels come from the rate's label. Do not concatenate a hard-coded percent next to a price that WooCommerce has already formatted with or without tax.

package/skills/vector-product-search/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: vector-product-search
+description: "Add vector retrieval beside lexical product search, with one embedding per purchasable unit and exact SKU lookup kept first. Use when adding embedding search, hybrid ranking, or re-embedding after catalog edits."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Vector product search
+
+Use this skill when lexical search is not enough for paraphrased queries. Facets, stock, and lexical ranking stay in the marketplace search skill. This skill adds a vector index. It does not replace SKU and GTIN lookup.
+
+Do not claim a recall or conversion number. Choose a model, record its id and dimension, and measure queries you have labeled.
+
+## Procedure
+
+1. Embed one text per purchasable unit. A variant with its own title or attributes gets its own vector. Copy the parent name into that text.
+2. Use the same model, dimension, and similarity metric for indexing and querying. Record `model_id` and a hash of the embedded text on the document.
+3. Keep price, stock, and facet ids as filter fields. Do not rely on the embedding to enforce "blue" or "in stock".
+4. Resolve an exact normalized SKU or GTIN before any vector query. If it hits one unit, return that unit first.
+5. Combine lexical and vector scores with a formula you write down. Re-embed when the text hash changes, not when only the price changes.
+
+Normalization and hybrid scoring are in [the index notes](references/index.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## What is embedded
+
+Include the fields a shopper might paraphrase: title, brand, category names, and attribute labels. Run the same text normalization as lexical search, including Persian Yeh, Kaf, digits, and ZWNJ removal, before you embed.
+
+Exclude price, stock counts, and SKUs from the embedded text. Price and stock change without the words changing, and a SKU is handled by exact match. If you later include them, the content hash must change when they change.
+
+## Query
+
+1. Normalize the query.
+2. Exact identifier match wins.
+3. Otherwise run the lexical query and the vector query with the same filters (facet ids, stock policy, category).
+4. Fuse the two ranked lists. A default you may start from is a weighted sum after each list is normalized to the same scale. Change the weight only when labeled queries say so.
+5. Page with a keyset on the fused score plus `unit_id`.
+
+Apply filters in both retrievals. A vector hit that ignores the selected color is a bug.
+
+## Re-embedding
+
+- Store `model_id`, dimension, metric (`cosine` unless the index documents another), and `text_hash`.
+- A catalog write recomputes the hash. If the hash or the model id differs, enqueue that unit.
+- Switching models rebuilds the index. Do not query an index with a different model than the one that wrote it.
+- Delete the vector when the unit is deleted. A parent rebuild replaces that parent's vectors as a set.
+
+## Gotchas
+
+- Embedding only the parent returns one vector for every size and color.
+- Cosine and dot product are not interchangeable unless the vectors are normalized and you meant that equivalence.
+- A vector score must not outrank an exact SKU match.
+- Indexing the raw Persian string and querying the normalized string misses. Normalize both.
+- Do not log shopper queries next to identifiers you are not allowed to retain. The query text can contain an address or a name the shopper pasted.
+
+## Verification
+
+- A SKU query returns that unit even when a nearer vector belongs to another product.
+- A color filter removes other colors from the vector results, not only from the lexical results.
+- Changing the price does not change `text_hash`. Changing the title does, and that unit is re-embedded.
+- Deleting a variant removes its vector.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/vector-product-search/evals/examples/reembed-on-title.md

@@ -0,0 +1,3 @@
+Store `model_id` and `text_hash` next to the vector.
+
+A title edit changes the hash and enqueues that unit. A price edit leaves the hash in place because price is a filter field.

package/skills/vector-product-search/evals/examples/sku-before-vector.md

@@ -0,0 +1,3 @@
+Normalize the query and look up `sku` and `gtin` first.
+
+Only if that lookup misses, run the vector query. The embedding text does not include the price.

package/skills/vector-product-search/evals/tasks.json

@@ -0,0 +1,30 @@
+{
+  "tasks": [
+    {
+      "id": "sku-before-vector",
+      "task": "Return the product whose SKU matches the query before any nearest-vector result.",
+      "expects": {
+        "must_include": [
+          "sku",
+          "vector"
+        ],
+        "must_not_include": [
+          "embedding of the price"
+        ]
+      }
+    },
+    {
+      "id": "reembed-on-title",
+      "task": "Re-embed a variant when its title changes and skip re-embedding when only the price changes.",
+      "expects": {
+        "must_include": [
+          "text_hash",
+          "model_id"
+        ],
+        "must_not_include": [
+          "cosine and dot product"
+        ]
+      }
+    }
+  ]
+}

package/skills/vector-product-search/references/index.md

@@ -0,0 +1,40 @@
+# Vector index beside lexical search
+
+## Document
+
+| Field | Role |
+| --- | --- |
+| `unit_id` | Purchasable unit. Primary key. |
+| `parent_id` | Set for variants. |
+| `sku`, `gtin` | Exact match. Not part of the embedded text. |
+| `text_hash` | Hash of the normalized text that was embedded. |
+| `model_id` | Embedding model identifier and its dimension. |
+| `embedding` | Vector from that model only. |
+| `facet_ids`, `in_stock`, `price`, `currency` | Filters and display. Not a reason to re-embed. |
+
+## Embedded text
+
+```text
+{title}
+{brand}
+{category names}
+{attribute labels}
+```
+
+Normalize with the marketplace search normalizer before hashing and embedding. The hash is of the normalized text. If you change the normalizer, rebuild the index. Old hashes would not match the new text.
+
+## Fusion
+
+Normalize each retrieval's scores onto `[0, 1]` within that result set, then:
+
+```text
+fused = (lexical_weight * lexical) + (vector_weight * vector)
+```
+
+Start at `lexical_weight = 0.6` and `vector_weight = 0.4` if you have no labeled queries yet. This is a starting point, not a measured optimum. Units that appear in only one list use `0` for the missing score.
+
+Exact SKU or GTIN matches skip fusion and are placed first.
+
+## Metric
+
+Write down cosine similarity or the index's metric next to `model_id`. Query with that metric. Do not mix cosine in one environment and inner product in another unless both sides use normalized vectors and you have recorded that they match.

package/skills/woocommerce-plugin-development/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: woocommerce-plugin-development
+description: "Build and change WooCommerce plugins with hooks, CRUD data stores, HPOS-safe order access, nonces, capabilities, and gettext. Use when writing or reviewing a plugin that reads or writes WooCommerce products, orders, customers, or checkout."
+license: MIT
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# WooCommerce plugin development
+
+Use this skill for a WordPress plugin that depends on WooCommerce. Use the REST API skill for an external HTTP client. Use the payment and webhook skills for capture and notification handling. Use the WordPress plugin security skill for the authorization details of any new endpoint.
+
+## Procedure
+
+1. Declare the dependency in the main plugin file. WordPress 6.5+ understands `Requires Plugins: woocommerce`. Set `WC tested up to` as well. WooCommerce only surfaces High-Performance Order Storage (HPOS) compatibility in the plugins list when that header is present.
+2. Stop direct requests with `defined( 'ABSPATH' ) || exit;`.
+3. Read and write products and orders through CRUD. Load with `wc_get_product()` or `wc_get_order()`, change setters, then call `save()` once. List orders with `wc_get_orders()`. Do not query `wp_posts` for `shop_order`.
+4. From the main plugin file, on `before_woocommerce_init`, declare feature compatibility. Pass `__FILE__` from that main file. Declare `custom_order_tables` only when every order read and write uses CRUD or `OrderUtil`. Declare `cart_checkout_blocks` only when checkout behavior also runs for the Checkout block.
+5. Hook the specific action. Cover both checkout stacks when the code runs during checkout. Open [the hook notes](references/hooks.md) before choosing one.
+6. Authorize every write with a capability and a nonce. A nonce is not authentication.
+7. Send user-facing strings through gettext with the plugin text domain.
+
+A skeleton header and the compatibility declaration are in [`assets/main-plugin-file.php`](assets/main-plugin-file.php). Copy it into a new plugin only after you delete the declaration you cannot yet keep.
+
+## Order and product writes
+
+```php
+$order = wc_get_order( $order_id );
+if ( ! $order ) {
+    return;
+}
+$order->update_meta_data( '_carrier_code', sanitize_text_field( $carrier ) );
+$order->save();
+```
+
+Do not call `update_post_meta()`, `get_post_meta()`, `wp_insert_post()`, or `get_posts()` for orders. Those use the posts tables. Under HPOS the order may be absent there, or the row may be a stale compatibility copy.
+
+HPOS is the default for new installations from WooCommerce 8.2 onward. Older shops may still use posts storage. CRUD serves both. Compatibility mode can mirror orders into posts; code that reads those posts still fails when a merchant turns the mirror off.
+
+Open [the HPOS notes](references/hpos.md) before adding an admin order screen, a custom order query, or SQL.
+
+## Checkout hooks
+
+Classic shortcode checkout and the Checkout block do not share one hook.
+
+- Classic checkout, before the first save: `woocommerce_checkout_create_order` receives the `WC_Order` and the posted data.
+- Classic checkout, after the order exists: `woocommerce_checkout_order_processed`.
+- Checkout block and Store API: `woocommerce_store_api_checkout_update_order_from_request` and `woocommerce_store_api_checkout_order_processed`.
+
+A plugin that hooks only the classic actions does not run during block checkout.
+
+## Admin order screens
+
+`wc_get_page_screen_id( 'shop-order' )` returns `shop_order` on posts storage and the HPOS orders screen id otherwise. Use it for metaboxes. The callback may receive a `WP_Post` or a `WC_Order`. Normalize with `wc_get_order()` and ignore the original argument after that. Link to an order with `$order->get_edit_order_url()`.
+
+`save_post_shop_order` does not run for HPOS orders. Persist admin fields from `woocommerce_process_shop_order_meta`, then `wc_get_order()` and `save()`.
+
+## Internationalization
+
+- The text domain matches the plugin slug. Set the `Text Domain` header.
+- Print with `esc_html__()`, `esc_attr__()`, and `esc_html_e()`. Use `sprintf` placeholders. Do not concatenate translated fragments.
+- Language packs for plugins hosted on WordPress.org load from the slug. For any other distribution, call `load_plugin_textdomain()` on `init`. WordPress 6.7 reports a notice when translations load earlier.
+- RTL layout is a separate task. Use the Persian and RTL skill when the storefront needs it.
+
+## Gotchas
+
+- `save()` writes the object. Set the fields for this change, then save once.
+- Refunds are orders of type `shop_order_refund`. Create them with `wc_create_refund()`. Flipping the parent status to `refunded` does not record a refund.
+- Stock reduction is tied to payment completion and status transitions. A second decrement double-counts. Core tracks this with `_order_stock_reduced` inside `wc_maybe_reduce_stock_levels()`.
+- `woocommerce_checkout_update_order_meta` still runs. Examples that call `update_post_meta()` inside it are not HPOS-safe.
+- Declaring `custom_order_tables` compatibility `true` is a promise. If any order path still uses post APIs, declare `false` until that path is gone.
+- SQL against `{$wpdb->prefix}wc_orders` skips caches and the posts fallback. Limit it to a measured report, and branch with `OrderUtil::custom_orders_table_usage_is_enabled()`.
+
+## Verification
+
+- With HPOS on and compatibility mode off, create and edit an order through the plugin. The change is visible in admin and in `wc_get_order()`.
+- If both checkouts are enabled, place one classic order and one block order.
+- A user without the required capability cannot perform the write. A missing or reused nonce is rejected.
+- New strings are escaped where printed and are picked up by `wp i18n make-pot`.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/woocommerce-plugin-development/assets/main-plugin-file.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Plugin Name: Example Commerce Plugin
+ * Description: Skeleton. Replace the name, slug, and compatibility flags before shipping.
+ * Version: 0.1.0
+ * Author: Replace with the plugin author
+ * Text Domain: example-plugin
+ * Requires Plugins: woocommerce
+ * Replace x.y.z below with the WooCommerce version you actually tested.
+ * WC tested up to: x.y.z
+ *
+ * @package ExamplePlugin
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+add_action(
+	'before_woocommerce_init',
+	static function () {
+		if ( ! class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
+			return;
+		}
+		// Keep true only when order access stays on CRUD. Otherwise pass false.
+		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
+		// Keep true only when checkout changes also run for the Checkout block.
+		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
+	}
+);

package/skills/woocommerce-plugin-development/evals/examples/declare-hpos.md

@@ -0,0 +1,9 @@
+Declare compatibility on the WooCommerce init hook from the main plugin file.
+
+```php
+add_action( 'before_woocommerce_init', function () {
+    \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
+} );
+```
+
+Include a WC tested up to header set to the version you actually tested.

package/skills/woocommerce-plugin-development/evals/examples/save-order-meta.md

@@ -0,0 +1,9 @@
+Load the order and write meta through CRUD.
+
+```php
+$order = wc_get_order( $order_id );
+$order->update_meta_data( '_carrier_code', $carrier );
+$order->save();
+```
+
+Check `edit_shop_orders` and a nonce before this write.

package/skills/woocommerce-plugin-development/evals/tasks.json

@@ -0,0 +1,32 @@
+{
+  "tasks": [
+    {
+      "id": "save-order-meta",
+      "task": "Store a carrier code from the WooCommerce order admin screen using CRUD so the value survives HPOS.",
+      "expects": {
+        "must_include": [
+          "wc_get_order",
+          "update_meta_data",
+          "->save("
+        ],
+        "must_not_include": [
+          "update_post_meta"
+        ]
+      }
+    },
+    {
+      "id": "declare-hpos",
+      "task": "Declare High-Performance Order Storage compatibility from the main plugin file after order access uses CRUD.",
+      "expects": {
+        "must_include": [
+          "before_woocommerce_init",
+          "declare_compatibility",
+          "custom_order_tables"
+        ],
+        "must_not_include": [
+          "save_post_shop_order"
+        ]
+      }
+    }
+  ]
+}

package/skills/woocommerce-plugin-development/references/hooks.md

@@ -0,0 +1,46 @@
+# WooCommerce hooks
+
+Confirm argument order in the WooCommerce version you are running when a signature is load-bearing. Prefer a hook that receives a `WC_Order` or `WC_Product`. If a hook passes only an id, load the object with `wc_get_order()` or `wc_get_product()` and do not touch post meta.
+
+## Orders
+
+| Hook | Use it for |
+| --- | --- |
+| `woocommerce_checkout_create_order` | Set order fields and meta during classic checkout, before the first save. |
+| `woocommerce_checkout_order_processed` | React after a classic checkout order exists. |
+| `woocommerce_store_api_checkout_update_order_from_request` | Same moment as classic create, for the Checkout block. |
+| `woocommerce_store_api_checkout_order_processed` | React after a block checkout order exists. |
+| `woocommerce_new_order` | Notice that an order id exists. Status may still be `pending` or `checkout-draft`. |
+| `woocommerce_order_status_changed` | Compare previous and next status. Arguments are order id, old status, new status, and the order. |
+| `woocommerce_payment_complete` | Run side effects after a verified payment. Do not use this as the only stock decrement. |
+| `woocommerce_order_refunded` | React after `wc_create_refund()` has created the refund order. |
+| `woocommerce_before_order_object_save` | Inspect or adjust an order about to be written through CRUD. |
+| `woocommerce_process_shop_order_meta` | Save admin order fields for both storage modes. |
+
+Do not use `save_post_shop_order` or `manage_edit-shop_order_columns` as the only integration point. The HPOS list table uses `woocommerce_shop_order_list_table_columns` and `woocommerce_shop_order_list_table_custom_column`. Register the custom-column action with two accepted arguments. The second is a `WC_Order`, not a post id.
+
+## Products
+
+| Hook | Use it for |
+| --- | --- |
+| `woocommerce_before_product_object_save` / `woocommerce_after_product_object_save` | Changes made through `WC_Product::save()`. |
+| `woocommerce_new_product` / `woocommerce_update_product` | After a product id exists. |
+| `woocommerce_product_options_general_product_data` | Extra fields on the product data panel. |
+| `woocommerce_process_product_meta` | Save those fields. Check a nonce and `edit_products`. |
+| `woocommerce_product_set_stock` / `woocommerce_variation_set_stock` | React to a stock write. Do not write stock again from the same hook. |
+
+## Cart and checkout fields
+
+| Hook | Use it for |
+| --- | --- |
+| `woocommerce_add_to_cart_validation` | Reject a line before it enters the cart. Return false and add a notice. |
+| `woocommerce_before_calculate_totals` | Change line prices for this request. Guard with a flag so the hook does not recurse. |
+| `woocommerce_cart_calculate_fees` | Add a fee. Fees are not a substitute for a payment surcharge unless the store shows the fee before the pay button. |
+| `woocommerce_checkout_fields` | Add, remove, or relabel classic checkout fields. |
+| `woocommerce_default_address_fields` | Change address fields for every country, then override per country with `woocommerce_get_country_locale`. |
+
+## Registration
+
+Register gateways on `woocommerce_payment_gateways`. Register settings on `woocommerce_get_settings_{tab}`.
+
+Run WooCommerce callbacks after WooCommerce has loaded. `plugins_loaded` at the default priority is too early if your plugin file loads before WooCommerce. Prefer `woocommerce_loaded`, or a later `plugins_loaded` priority, before calling `wc_get_order()` during bootstrap.

package/skills/woocommerce-plugin-development/references/hpos.md

@@ -0,0 +1,84 @@
+# HPOS order access
+
+High-Performance Order Storage keeps orders in dedicated tables:
+
+- `{prefix}wc_orders`
+- `{prefix}wc_order_addresses`
+- `{prefix}wc_order_operational_data`
+- `{prefix}wc_orders_meta`
+
+Posts storage keeps the same objects in `wp_posts` and `wp_postmeta` as the `shop_order` post type. Refunds use `shop_order_refund` in both modes. CRUD hides that choice. Direct SQL and post APIs do not.
+
+## Detect the active store
+
+```php
+use Automattic\WooCommerce\Utilities\OrderUtil;
+
+$hpos = class_exists( OrderUtil::class ) && OrderUtil::custom_orders_table_usage_is_enabled();
+```
+
+Use this to branch SQL or admin screen registration. Do not use it to decide whether `wc_get_order()` works. That function works in both modes.
+
+## Declare compatibility
+
+Call this from the main plugin file. `declare_compatibility()` returns false outside `before_woocommerce_init`.
+
+```php
+add_action( 'before_woocommerce_init', function () {
+    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
+        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
+    }
+} );
+```
+
+If the declaration lives in another file, pass the main plugin file path, such as `example-plugin/example-plugin.php`, instead of `__FILE__`.
+
+## Queries
+
+```php
+$results = wc_get_orders(
+    array(
+        'status'   => array( 'processing', 'completed' ),
+        'limit'    => 50,
+        'paginate' => true,
+        'return'   => 'objects',
+    )
+);
+```
+
+Filter custom meta with `meta_query` only when the cardinality is small enough to measure. There is no unique index on arbitrary meta keys. An idempotency lookup by meta is not a uniqueness constraint.
+
+Identify an order with `OrderUtil::is_order()` and `OrderUtil::get_order_type()`. Do not call `get_post_type()` for this.
+
+## Admin metabox
+
+```php
+add_action( 'add_meta_boxes', function () {
+    if ( ! function_exists( 'wc_get_page_screen_id' ) ) {
+        return;
+    }
+    add_meta_box(
+        'example_order_panel',
+        __( 'Shipping desk', 'example-plugin' ),
+        'example_render_order_panel',
+        wc_get_page_screen_id( 'shop-order' ),
+        'side'
+    );
+} );
+
+function example_render_order_panel( $post_or_order ) {
+    if ( ! current_user_can( 'edit_shop_orders' ) ) {
+        return;
+    }
+    $order = $post_or_order instanceof WC_Order ? $post_or_order : wc_get_order( $post_or_order->ID ?? 0 );
+    if ( ! $order ) {
+        return;
+    }
+    wp_nonce_field( 'example_order_panel', 'example_order_nonce' );
+    echo esc_html( $order->get_order_number() );
+}
+```
+
+## Sync mode is not compatibility
+
+While "Enable compatibility mode" is on, WooCommerce copies orders between the two stores. A plugin can appear to work because it reads the copy. Turn compatibility mode off in a staging shop and repeat the order flow before declaring `custom_order_tables` compatible.