wordpress-agent-kit 0.5.1 → 0.6.0

package/.github/skills/wp-abilities-api/references/delegate-helper-pattern.md

@@ -1,241 +0,0 @@
-# Delegate helper pattern
-
-Once you've decided delegation is the right shape for an ability — that is, the backing REST controller is a pure data-fetch, the operation is a read, and the ability runs predominantly inside REST contexts (see `shared-core-service.md` for when the answer is "no, extract a shared service" instead) — extract a `delegate_to_rest_controller` helper rather than open-coding the request-build/dispatch/unwrap pipeline in each execute callback. This reference documents one helper shape that works, the three guards every implementation needs, the dual response-shape unwrap, and when NOT to use the helper at all. Adapt the exact signature to the plugin you're working in — the guards and unwrap matter more than the parameter list.
-
-Read `plugin-family-patterns.md` first — the helper's exact shape depends on how the backing controller is constructed (shared API client vs. zero-arg).
-
-## Why this helper exists
-
-List-style read abilities typically repeat the same four steps in every execute callback:
-
-1. Validate the plugin is initialized (class exists + dependencies resolved).
-2. Build a `WP_REST_Request` and copy the ability's `$input` onto it as params.
-3. Instantiate the backing controller and invoke the named method.
-4. Unwrap the response (controllers return either a raw array or a `WP_REST_Response`).
-
-Four abilities × this repetition = the boilerplate dominates the callback body. Extracting a helper keeps each execute callback a 3–4 line function that reads like pseudocode.
-
-## When to extract
-
-After the **second** list-style ability lands. Before the third ability gets added, refactor the duplicated code out of the first two execute callbacks into a private static helper. Convert subsequent abilities to call the helper as you add them.
-
-If the plugin only ever ships one or two abilities, inline the code. The helper's payoff is at 3+ callers.
-
-## Helper shape
-
-```php
-/**
- * Delegate an ability's execute callback to a REST controller.
- *
- * Builds a WP_REST_Request from the ability's input, instantiates the
- * backing controller with the plugin's shared API client, invokes the
- * named method, and normalizes the return so callers always see
- * array|\WP_Error. Controllers in this plugin return either a
- * WP_REST_Response or a raw array; the helper unwraps both shapes.
- *
- * Not used by zero-arg abilities — those call their controller directly
- * so we don't synthesize a WP_REST_Request just to discard it.
- *
- * @param string     $controller_class Fully-qualified controller class (no leading backslash).
- * @param string     $method           Controller method to invoke on the built request.
- * @param string     $route            REST route string used when constructing WP_REST_Request.
- * @param array|null $input            Ability input; each key/value becomes a request param.
- * @param string     $http_method      HTTP method for WP_REST_Request. Defaults to 'GET'; writes pass 'POST'.
- * @return array|\WP_Error             Response payload as an array, or WP_Error on failure.
- */
-private static function delegate_to_rest_controller(
-    $controller_class,
-    $method,
-    $route,
-    $input,
-    $http_method = 'GET'
-) {
-    $fqcn = '\\' . $controller_class;
-
-    // Guard 1: controller class is loaded.
-    if ( ! class_exists( $fqcn ) ) {
-        return new \WP_Error(
-            '<plugin>_not_initialized',
-            __( '<Plugin> is not initialized.', '<text-domain>' )
-        );
-    }
-
-    // Guard 2: shared API client is available.
-    $api_client = null;
-    if ( class_exists( '\<Plugin_Main_Class>' ) && method_exists( '\<Plugin_Main_Class>', 'get_<client_accessor>' ) ) {
-        $api_client = \<Plugin_Main_Class>::get_<client_accessor>();
-    }
-    if ( null === $api_client ) {
-        return new \WP_Error(
-            '<plugin>_not_initialized',
-            __( '<Plugin> is not initialized.', '<text-domain>' )
-        );
-    }
-
-    // Build the request.
-    $request = new \WP_REST_Request( $http_method, $route );
-    if ( null !== $input ) {
-        foreach ( $input as $param => $value ) {
-            $request->set_param( $param, $value );
-        }
-    }
-
-    // Invoke + guard 3: WP_Error short-circuit + dual-shape unwrap.
-    $controller = new $fqcn( $api_client );
-    $response   = $controller->{$method}( $request );
-
-    if ( is_wp_error( $response ) ) {
-        return $response;
-    }
-    if ( $response instanceof \WP_REST_Response ) {
-        $data = $response->get_data();
-        return is_array( $data ) ? $data : [];
-    }
-    return is_array( $response ) ? $response : [];
-}
-```
-
-Positional (not named) arguments on purpose — the helper is called from every list ability and keyword-args for PHP 8 would add visual noise. Order is intentional: controller, method, route, input, http_method (the defaultable tail).
-
-## The three guards
-
-### 1. `class_exists` on the controller
-
-Execute callbacks can be reached on sites where the plugin's classes haven't loaded (tests, WP-CLI with limited bootstrap, admin pages with conditional autoloading). Check is cheap; without it a missing class produces a fatal.
-
-Note `'\\' . $controller_class` — accept controller class names without a leading backslash (readable in config arrays) and re-add it so `class_exists` and `new $fqcn(...)` both root-resolve.
-
-### 2. Required dependency (API client) null-check
-
-When the controller takes a shared API client as a constructor argument, the accessor is typically a `public static` method on the main plugin class. Guard both `class_exists` on the plugin class AND `method_exists` on the accessor because either could be absent during partial bootstraps. Treat a null return from the accessor as "not initialized".
-
-Missing this argument produces `ArgumentCountError: Too few arguments to function <Controller>::__construct(), 0 passed` — a PHP fatal. The standardized `<plugin>_not_initialized` error code is documented in `error-code-vocabulary.md`.
-
-When the controller takes no constructor args, skip this guard entirely. When it takes only simple scalars (e.g. a post-type string), pass them in via an optional `constructor_args` parameter on the helper.
-
-### 3. `is_wp_error` short-circuit
-
-Before trying to unwrap the response, check if it's already a `WP_Error`. Several controllers return `WP_Error` for both validation failures and upstream failures; that error needs to bubble up intact so the agent can see the upstream code.
-
-## Dual response-shape unwrap
-
-```php
-if ( $response instanceof \WP_REST_Response ) {
-    $data = $response->get_data();
-    return is_array( $data ) ? $data : [];
-}
-return is_array( $response ) ? $response : [];
-```
-
-Real WordPress REST controllers return either:
-- A `WP_REST_Response` (the output of `rest_ensure_response( ... )` or `new WP_REST_Response( ... )`), or
-- A raw array (typical when a controller delegates to an internal request-handler class that returns the decoded transport payload directly).
-
-Both happen. The helper unwraps `WP_REST_Response` via `get_data()` and passes raw arrays through. The `is_array(...) ? ... : []` coalesce defends against a non-array return type that the ability's `output_schema` would have rejected downstream anyway — returning `[]` fails safely rather than leaking a surprising type.
-
-## When NOT to use the helper
-
-Three categories of abilities bypass the helper and call the backing directly:
-
-### Backing request class can be invoked without the controller
-
-If the REST controller's only role is to translate `WP_REST_Request` into a call to an underlying request class (e.g., `Things_Request::from_rest_request( $request )->execute()`) and adds no validation, permission logic, or orchestration on top, bypass the controller and call the request class directly:
-
-```php
-public static function execute_get_things( $input = null ) {
-    if ( ! class_exists( '\My_Plugin\Things_Request' ) ) {
-        return new \WP_Error( '<plugin>_not_initialized', __( '<Plugin> is not initialized.', '<text-domain>' ) );
-    }
-
-    $request = new \WP_REST_Request( 'GET', '/my-plugin/v1/things' );
-    foreach ( (array) $input as $param => $value ) {
-        $request->set_param( $param, $value );
-    }
-
-    $things_request = \My_Plugin\Things_Request::from_rest_request( $request );
-    $rows           = $things_request->execute();
-
-    return is_array( $rows ) ? $rows : [];
-}
-```
-
-The `WP_REST_Request` object exists only to satisfy `from_rest_request()`'s parameter contract — nothing dispatches it. This is the shortest path through the layers: no controller construction, no controller-emitted side effects, and (when the request class is hit before any REST traffic in the lifecycle) no `rest_api_init` cost. See `shared-core-service.md` for the broader discussion of REST-path side effects and the first-call bootstrap cost on cold paths.
-
-The tradeoff is real: bypassing the controller bypasses anything the controller does. If the controller runs validation that the request class doesn't, or emits an audit hook the request class doesn't, that work is lost on the ability path. Use this shape when the controller is genuinely a thin wrapper, not when it's doing work you'd want to keep.
-
-### Zero-arg backing methods
-
-If the backing method takes no `WP_REST_Request` parameter, don't synthesize a request just to discard it. Call the method directly:
-
-```php
-public static function execute_get_overview( $input = null ) {
-    if ( ! class_exists( '\My_Plugin_REST_Overview_Controller' ) ) {
-        return new \WP_Error( '<plugin>_not_initialized', __( '<Plugin> is not initialized.', '<text-domain>' ) );
-    }
-
-    $api_client = /* ... same accessor check ... */;
-    if ( null === $api_client ) {
-        return new \WP_Error( '<plugin>_not_initialized', __( '<Plugin> is not initialized.', '<text-domain>' ) );
-    }
-
-    $controller = new \My_Plugin_REST_Overview_Controller( $api_client );
-    $response   = $controller->get_overview(); // No $request argument.
-
-    if ( is_wp_error( $response ) ) {
-        return $response;
-    }
-    return is_array( $response ) ? $response : [];
-}
-```
-
-### Abilities that use a non-REST service
-
-If the execute callback reaches a service directly (e.g. `My_Plugin::get_account_service()->get_cached_account_data()`) rather than a REST controller, stay on the direct path. The ability is not REST-backed and the helper would add a construction step for no gain.
-
-## Rule of thumb
-
-**If the backing method takes `WP_REST_Request` and the controller adds something beyond delegating to an underlying request class (validation, permissions, orchestration, side effects you want to keep), use the helper. If the controller is a thin wrapper over a request class, call the request class directly. Otherwise direct-path.**
-
-## Conversion pattern — before and after
-
-Before extraction (inline in the execute callback):
-
-```php
-public static function execute_get_things( $input = null ) {
-    if ( ! class_exists( '\My_Plugin_REST_Things_Controller' ) ) {
-        return new \WP_Error( '<plugin>_not_initialized', __( '<Plugin> is not initialized.', '<text-domain>' ) );
-    }
-    $api_client = \My_Plugin::get_api_client();
-    if ( ! $api_client ) {
-        return new \WP_Error( '<plugin>_not_initialized', __( '<Plugin> is not initialized.', '<text-domain>' ) );
-    }
-    $request = new \WP_REST_Request( 'GET', '/my-plugin/v1/things' );
-    foreach ( (array) $input as $param => $value ) {
-        $request->set_param( $param, $value );
-    }
-    $controller = new \My_Plugin_REST_Things_Controller( $api_client );
-    $response   = $controller->get_things( $request );
-    // ... unwrap ...
-}
-```
-
-After extraction:
-
-```php
-public static function execute_get_things( $input = null ) {
-    return self::delegate_to_rest_controller(
-        'My_Plugin_REST_Things_Controller',
-        'get_things',
-        '/my-plugin/v1/things',
-        is_array( $input ) ? $input : null
-    );
-}
-```
-
-Note the `is_array( $input ) ? $input : null` — the helper signature is `?array`, and passing `null` tells it to build the request with no params at all. This matters because the Abilities API sometimes invokes a callback with no input object.
-
-## Related references
-
-- `plugin-family-patterns.md` — choosing the helper's constructor shape.
-- `error-code-vocabulary.md` — the `<plugin>_not_initialized` code and its siblings.
-- `input-schema-gotchas.md` — callbacks for list abilities often need `per_page` pagination translation BEFORE calling the helper.

package/.github/skills/wp-abilities-api/references/domain-vs-projection.md

@@ -1,113 +0,0 @@
-# Domain capability vs projection — picking the layer to register at
-
-> Three layers in this model: **domain**, **projection**, and an optional **workflow** layer that composes abilities into multi-step tasks. The title names the two primary decisions; workflow is introduced where it earns its keep.
-
-The Abilities API can be used at two heights. You can register abilities as the surface an MCP/REST/Command-Palette client will consume directly. Or you can register abilities at the domain layer — "what can this plugin do, transport-neutrally?" — and let each consumer see a projection of that surface that suits its constraints. This reference covers why the second framing pays off, the three-layer model that operationalizes it, and how to use it when deciding what to register.
-
-## Why this matters
-
-Treating MCP exposure as the registration target conflates two decisions:
-
-1. What capabilities does this plugin offer?
-2. How should each consumer see them?
-
-The first decision is stable. The second is volatile — token budgets shift, MCP clients improve, Command Palette gains new conventions, large plugins outgrow flat tool lists and adopt nested-discovery patterns. Coupling the two means re-registering abilities every time the projection question is reopened.
-
-Decoupling them means registrations stay where they are while projections evolve underneath.
-
-## The three layers
-
-| Layer | Purpose | Examples |
-|---|---|---|
-| **Domain capability** | Stable, transport-neutral, permission-checked. The plugin's contract for "what can this do." | `myplugin/list-things`, `myplugin/update-thing`, `myplugin/get-overview` |
-| **Workflow** *(optional)* | Compositions of one or more abilities into a human- or agent-friendly task. | "Onboard a new merchant" = `verify-account` → `enable-feature` → `send-welcome` |
-| **Projection** | Consumer-specific view of the domain layer. Token-efficient compression for MCP, curated workflows for Command Palette, discoverable execution surface for REST, forms for admin UI, chainable commands for CLI. | The bundled WordPress MCP adapter projects every published ability through three meta-abilities (`mcp-adapter/discover-abilities`, `mcp-adapter/execute-ability`, `mcp-adapter/get-ability-info`) — agents traverse those three rather than seeing the full registry flat. Command Palette, by contrast, can show the same domain abilities flat because token budget is not a constraint. |
-
-The domain layer is what the registry holds. The projection layer is what each consumer sees. The workflow layer is optional and exists when a user-or-agent-meaningful task needs more than one ability.
-
-## The use-case-contract test
-
-A registered ability is a use-case contract — a natural-language shortcut to an action a human can already perform in the UI. REST endpoints and CLI commands are transport contracts; they expose plumbing. Abilities expose actions.
-
-Two consequences fall out of that framing:
-
-### 1. Inclusion test — "would a human intentionally do this through a supported UI or workflow?"
-
-If yes, the operation is a candidate for an ability. The lens is broader than wp-admin alone: a "supported UI or workflow" covers admin screens, public-facing UIs (storefront, account dashboard, course viewer, appointment booker), end-user self-service flows on the site front-end, and supported workflows in which another plugin or an agent calls the operation as part of a chain of actions. Abilities like `store/get-my-orders`, `events/list-available-tickets`, or `profile/update-public-profile` qualify just as much as admin-side abilities like `myplugin/list-pending-orders` or `myplugin/approve-submission`.
-
-If no, the operation stays a REST endpoint, a CLI command, or an internal hook. Internal-only plumbing — cache invalidation, scheduler ticks, debug snapshots, lifecycle bookkeeping — does not belong as an ability even when it has a clean schema. There is no meaningful human invocation point, so there is no use-case contract to register.
-
-The test is asymmetric: not everything a UI exposes should be an ability either (rule 1 in `grouping-heuristic.md` covers grouping). But anything that has no human-meaningful invocation surface almost certainly is not ability-meaningful.
-
-### 2. Same code path as the UI
-
-If the ability mirrors a UI action, it must share the UI's permissions, validation, and business rules. The mechanism for keeping that promise is in `shared-core-service.md`. The framing is here: the ability is the use-case; UI / REST / CLI / MCP are thin adapters over it.
-
-## Implications
-
-### You may register abilities you do NOT expose via MCP
-
-The Abilities API is a WordPress core primitive. It establishes a formal contract for "run this code with these inputs under this permission check." MCP, REST, and Command Palette are exposure layers on top. You opt in.
-
-This means a plugin can register abilities that the Command Palette uses but MCP does not see, or vice versa. The registration is transport-neutral; exposure is per-consumer.
-
-### The same domain ability can appear in multiple projections with different shapes
-
-A small plugin might expose its three abilities flat in MCP and flat in Command Palette. A larger plugin might keep the same three domain abilities but project them through a nested-discovery facade for MCP (three meta-tools that traverse to the underlying registrations) while showing them flat in the Command Palette where token budget is not a constraint.
-
-The domain layer does not change. The projection layer does the consumer-specific work.
-
-### Token-efficiency tradeoffs live at the projection layer
-
-The choice between flat-with-full-schemas, semantic-grouping, single-tool-facade, and nested-discovery is a *projection* decision. Different shapes serve different consumer constraints. None of those shapes require changing what abilities are registered at the domain layer; they change how a consumer sees the registered set.
-
-This is what "pattern-agnostic" means in practice: the registration is one decision, the projection is another, and a redesign of the second does not invalidate the first.
-
-## Decision order
-
-When designing a plugin's ability surface, work in this order:
-
-1. **Domain first.** What can this plugin do, transport-neutrally? Use the inclusion test. Apply `grouping-heuristic.md` to pick the right granularity (semantic-intent over REST-atomization).
-2. **Projection second.** Which surfaces does each capability appear on, and in what shape? For most plugins under ~10 abilities, flat-in-every-projection works. For larger plugins, consider nested-discovery for MCP while keeping flat for Command Palette and REST.
-3. **Workflow third (only if needed).** Are there multi-ability tasks worth composing into a single user-or-agent-facing entry point? If yes, the workflow lives above the domain layer and references multiple abilities.
-
-Most plugins never need step 3.
-
-## Worked example — generic Notifications plugin
-
-A "Notifications" plugin manages a per-user notification feed. It supports listing, marking read, and dismissing all.
-
-### Domain layer
-
-Three abilities, registered once:
-
-- `notifications/list` — read; filter by `unread_only`, `since`, `category`.
-- `notifications/mark-read` — write; takes a `notification_id`.
-- `notifications/dismiss-all` — write; zero-arg.
-
-These are use-case contracts. They are transport-neutral. They do not assume MCP or Command Palette or REST.
-
-### Projection — MCP
-
-Small surface, flat works. The MCP projection exposes the three abilities as-is. No nested-discovery needed.
-
-### Projection — Command Palette
-
-The Command Palette projection adds a small workflow that wraps `notifications/list` with default filters (`unread_only=true`) and opens the admin notifications page on selection. The other two abilities remain visible as flat commands. The domain registration did not change; the Command Palette layer added the workflow on top.
-
-### Projection — REST
-
-The REST projection exposes only the read ability. Writes go through admin UI for security-review reasons. The domain registration is unchanged; the REST layer just doesn't expose two of the three.
-
-Same three registrations, three different projections, no re-registration as projection decisions evolve.
-
-## Escape hatch — tiny plugins
-
-For plugins with one to three admin-only abilities and no other surfaces, the projection layer is trivially the identity function. You don't need to *implement* layers; you need to *think* in layers so you don't paint yourself into a corner when the plugin grows or when MCP token budgets become a constraint.
-
-Concretely: name the abilities at the domain level (`myplugin/get-thing`, not `myplugin-mcp/get-thing`), keep the registration permission-checked and transport-neutral, and skip the projection layer until something needs it.
-
-## Related references
-
-- `grouping-heuristic.md` — within-domain decisions: how many abilities, where to put filters.
-- `shared-core-service.md` — the implementation mechanism for "same code path as the UI."

package/.github/skills/wp-abilities-api/references/error-code-vocabulary.md

@@ -1,123 +0,0 @@
-# Error code vocabulary
-
-Every `WP_Error` returned from an ability's execute callback should use a code drawn from this small vocabulary. A consistent vocabulary lets the agent (or the caller in your automation) build retry and recovery logic that matches on codes instead of parsing error messages.
-
-## Why standardized codes matter
-
-Agents that orchestrate multiple abilities need to know: "did this fail because of my input, or because something downstream is unreachable?" The answer drives retry strategy:
-
-- Bootstrap failures → surface to the human, don't retry.
-- Input shape errors → fix the input and retry the same call.
-- Transient backend errors → retry with backoff; may succeed on its own.
-- Upstream third-party errors → may need a different strategy entirely.
-
-Without a convention, every plugin invents its own codes and agents can't reason uniformly across them. The categories below cover 95% of real-world ability errors; sticking to them means an agent that learned the retry logic for one plugin can reuse it for the next.
-
-## Vocabulary
-
-Substitute `<plugin>` with the plugin's slug in lowercase, underscores only. This matches WordPress error-code conventions. If the plugin already has a house style — for example, a single-word slug that deliberately omits underscores between elided words — mirror that. Consistency within a plugin trumps consistency across the vocabulary.
-
-| Code | When to use | Agent behavior |
-|---|---|---|
-| `<plugin>_not_initialized` | Plugin class missing, shared service accessor returns null, required dependency isn't resolvable. | Not retriable from the agent side. Usually a config or bootstrap-ordering problem. Escalate. |
-| `<plugin>_missing_<field>` | A required input field is missing or empty (your execute callback's own check, not the schema-validator's). | Agent should add the field and retry. |
-| `<plugin>_invalid_<field>` | Field is present but semantically wrong (bad enum value, malformed date, wrong type). | Agent should correct the value and retry. |
-| `<plugin>_<resource>_data_unavailable` | Backing service returned a transient error (cache miss + remote failure, upstream 5xx, stale-while-revalidate failed). | Agent can retry, probably with backoff. |
-| `ability_invalid_input` | The Abilities API's own schema-validator rejected the input before the execute callback ran. | Equivalent to `<plugin>_missing_<field>` or `<plugin>_invalid_<field>`, just thrown earlier in the pipeline. Agent should fix input. |
-
-### `ability_invalid_input` — the earlier path
-
-When an ability is invoked via the Abilities API REST bridge, the registered `input_schema` runs first. Missing required fields or type mismatches produce `WP_Error( 'ability_invalid_input' )` BEFORE the execute callback fires. Direct invocation (unit tests, non-REST wrappers) bypasses schema validation and hits your execute callback's own checks instead, producing `<plugin>_missing_<field>` / `<plugin>_invalid_<field>`.
-
-Both paths are acceptable — end-agent-facing behavior is equivalent (deterministic validation error, no side effects). Document the observation in the ability's PR description or "notes for reviewers" so reviewers know both codes are expected in different harness runs.
-
-## Worked examples
-
-```php
-// Bootstrap incomplete — plugin class missing or accessor returned null.
-return new \WP_Error(
-    '<plugin>_not_initialized',
-    __( '<Plugin> is not initialized.', '<text-domain>' )
-);
-
-// Required field missing (execute-callback check, schema was bypassed).
-return new \WP_Error(
-    '<plugin>_missing_<field>',
-    __( 'A <field> is required to <do the thing>.', '<text-domain>' )
-);
-
-// Field present but malformed.
-return new \WP_Error(
-    '<plugin>_invalid_<field>',
-    sprintf(
-        /* translators: %s: input parameter name. */
-        __( 'The "%s" parameter must be an ISO 8601 date-time string.', '<text-domain>' ),
-        $key
-    )
-);
-
-// Transient backend error.
-return new \WP_Error(
-    '<plugin>_<resource>_data_unavailable',
-    __( 'Unable to retrieve <resource> data. The cache may be stale or the remote service returned an error.', '<text-domain>' )
-);
-```
-
-## Upstream codes can bubble through — and usually should
-
-If the backing controller talks to a third-party API (Stripe, WPCOM, another SaaS), its own error codes may surface verbatim in `WP_Error::get_error_code()` the ability returns. Typical examples:
-
-- `resource_missing` — Stripe's "object ID not found" code. Tells an agent the specific ID was wrong.
-- `rate_limited` — upstream throttling. Tells an agent to slow down.
-
-**Let these through rather than re-wrapping.** A re-wrapped `<plugin>_<resource>_not_found` loses the information that would help the agent act. Document the upstream codes you've observed in the ability's `description` or PR notes so reviewers know they're expected.
-
-## Code naming rules
-
-1. **Lowercase, underscores only.** `<plugin>_missing_order_id`, not `<plugin>-missingOrderId` or `<Plugin>-MissingOrderId`.
-2. **Plugin prefix first.** Multi-word slugs should normalize to a single-word prefix where the plugin already does (e.g. `woopayments` rather than `woo_payments`).
-3. **Action second.** Use one of `missing`, `invalid`, `not_initialized`, `<resource>_data_unavailable`.
-4. **Field or resource name last.** `<plugin>_missing_dispute_id`, not `<plugin>_dispute_id_missing`. This matches English phrasing ("a dispute_id is required") and is faster to skim in error logs.
-
-## Internationalization
-
-Error MESSAGES are translatable via `__()` or `sprintf(__())`. Error CODES are not — they're stable machine identifiers.
-
-```php
-// WRONG — don't translate the code.
-return new \WP_Error( __( '<plugin>_missing_order_id', '<text-domain>' ), ... );
-
-// RIGHT — code is a literal, message is translatable.
-return new \WP_Error(
-    '<plugin>_missing_order_id',
-    __( 'An order_id is required.', '<text-domain>' )
-);
-```
-
-When a message interpolates a parameter name or value, include a translator comment:
-
-```php
-return new \WP_Error(
-    '<plugin>_invalid_date',
-    sprintf(
-        /* translators: %s: input parameter name. */
-        __( 'The "%s" parameter must be an ISO 8601 date-time string.', '<text-domain>' ),
-        $key
-    )
-);
-```
-
-## Don't over-specify
-
-The goal is consistent codes across all of a plugin's abilities, not ultra-fine granularity. `<plugin>_missing_dispute_id` is the right level. `<plugin>_missing_dispute_id_in_submit_evidence_context` is not — the ability name belongs in `WP_Error::get_error_data()` or in the agent's calling context, not in the code.
-
-## Summary — the four questions
-
-When writing an execute callback, ask in order:
-
-1. Can the plugin even service this call? → `<plugin>_not_initialized`.
-2. Is the required input present? → `<plugin>_missing_<field>`.
-3. Is the required input the right shape? → `<plugin>_invalid_<field>`.
-4. Did the backing service choke? → `<plugin>_<resource>_data_unavailable`, or let the upstream code bubble through.
-
-Four categories, one consistent code vocabulary per plugin. That's enough for agents to build reliable retry logic on top.

package/.github/skills/wp-abilities-api/references/grouping-heuristic.md

@@ -1,89 +0,0 @@
-# Grouping heuristic — domain-layer granularity
-
-How to decide WHAT to register when a plugin already has a REST (or internal service) surface. The hard part of adopting the Abilities API is not the registration syntax — it's picking the right *domain-layer granularity* so abilities map to user-meaningful actions instead of HTTP plumbing.
-
-> **Scope note.** This reference governs *domain-layer* decisions: how many abilities to register, where to put filters vs. where to introduce a new ability name. It does NOT govern projection-layer choices (flat-with-full-schemas vs single-tool facade vs nested-discovery vs semantic grouping in the consumer view). Those are separate decisions made *after* the domain layer is settled — see `domain-vs-projection.md` for the layering. A domain layer chosen well is reusable across multiple projections; conflating the two means re-registering every time a consumer's constraints change.
-
-## Three observed approaches
-
-| Approach | Shape | Example | Verdict (domain-layer) |
-|---|---|---|---|
-| **Action-bundle** | One ability bundles many sub-operations behind an action string. | `my_plugin_account` with `action: "get" \| "update" \| "delete"`. | **Avoid.** Hides the ability surface from the agent's tool-list and defeats the Abilities API's introspection model — agents can't see what a bundle can do until they invoke it. |
-| **REST-atomization** | One ability per HTTP method per resource (typically 5 per resource: list, get, create, update, delete). | `orders-list`, `orders-get`, `orders-create`, `orders-update`, `orders-delete`. | **Avoid as the registration shape.** Couples ability names to HTTP plumbing rather than user intent — and forces re-registration if the projection layer ever needs to compress the surface. |
-| **Semantic-intent** | One ability per real-world question or state transition. Filter parameters in `input_schema` collapse N variants into 1. | One `feedback/get-responses` ability with `status`, `is_unread`, `search`, and date-range filters in `input_schema` — replaces what would be 8+ atomized variants. | **Recommended for the domain layer.** |
-
-## Why semantic-intent wins at the domain layer
-
-1. **Users think in questions, not HTTP verbs.** "Which form responses are unread?" maps cleanly to one ability with an `is_unread` filter. It does NOT map to 8 abilities (`get-unread-responses`, `get-spam-responses`, `get-trashed-responses`, ...). Ability names are *use-case contracts* — see `./domain-vs-projection.md`.
-2. **The Abilities API's `input_schema` is designed for rich inputs.** Enum constraints, date-time formats, and required-field validation do the variant-splitting job that atomization would delegate to the ability name.
-3. **Writes stay narrow anyway.** A write ability should already be one state transition; atomization and semantic-intent converge for writes.
-4. **Tool-list token cost is a downstream consequence, not the reason.** Semantic-intent registrations also serialize cheaper in flat MCP projections — but token cost is a *projection-layer* concern. If registrations are cheap by accident because the use-case framing happened to compress them, that's a happy side-effect; if they're expensive, the fix is at the projection layer (single-tool facade, nested-discovery), not by re-grouping the domain.
-
-## Rules that make it work
-
-### 1. Group reads by the question a user would type
-
-Draft the question in plain English. That question is the ability. The filter parameters go in `input_schema`.
-
-- WRONG: one ability per status value.
-- RIGHT: one `get-<resource>` ability with `status: { type: "string", enum: [...] }`.
-
-### 2. Keep writes narrow — one state transition per ability
-
-A write ability should do exactly one thing the agent can reason about in isolation and explain to a user. Different state transitions → different abilities (different consequences, different annotations, different permission implications).
-
-- WRONG: `update-resource` that branches internally on an action enum.
-- RIGHT: `submit-evidence` and `close-resource` as separate abilities.
-
-### 3. Prefer 1 ability with filter params over N abilities with no params
-
-Ask: "if the backing added a new filter value, would that create a new ability?" If not, the filter belongs in `input_schema`, not in the ability name.
-
-### 4. Zero-arg overview abilities are high-leverage
-
-When enumerating the backing surface, specifically look for zero-argument aggregate or "overview" endpoints — "what's my balance?", "what's my next payout?", "what's my form response count?". These answer the highest-frequency user questions with zero input and zero room for agent error. Flag them even if they weren't in the original plan.
-
-### 5. Don't ship abilities you can't explain in one sentence
-
-Every ability's `label` + `description` should fit in an agent's tool-selection prompt. If you can't describe the ability in one sentence without "and", that's usually a sign it's two abilities.
-
-## Worked example A — feedback/responses: 3 abilities for the whole responses surface
-
-Consider a generic feedback or form-response plugin. Its admin screens expose: a list with 8+ filters, a detail view, bulk status changes (spam / trash / publish), read/unread toggles, and a count-by-status dashboard summary.
-
-REST-atomization would ship ~6 abilities (list, get, delete, update, bulk-update, count). Semantic-intent registers **three**:
-
-- `feedback/get-responses` — list/search, with `status`, `is_unread`, `search`, `before`, `after`, `parent` in `input_schema`.
-- `feedback/update-response` — one write that covers status changes AND read-state toggles on a single response (semantically "modify a response").
-- `feedback/get-status-counts` — the dashboard summary ability. Zero-arg-friendly (only optional filters).
-
-Why three works: a user asking "show me spam responses from last week" uses one ability. An agent updating one response to `spam` uses one ability. The dashboard-style "how many unread?" uses one ability. The entire product surface fits in three tool-list entries.
-
-## Worked example B — generic Tickets plugin: one ability with a status filter, not eight
-
-A hypothetical `myplugin-tickets` plugin manages a support-ticket queue. Its REST endpoint `GET /myplugin/v1/tickets` accepts `status`, `priority`, `assigned_to`, `tag`, `date_before`, `date_after`, `search`. Status values include `new`, `triaged`, `in_progress`, `waiting_customer`, `waiting_internal`, `resolved`, `closed`, `reopened` — eight in total.
-
-- Atomization would ship ~8 abilities (`get-tickets-new`, `get-tickets-resolved`, `get-tickets-closed`, ...).
-- Semantic-intent ships **one** — `myplugin-tickets/get-tickets` with `status: { type: "string", enum: ["new", "triaged", "in_progress", "waiting_customer", "waiting_internal", "resolved", "closed", "reopened"] }`.
-
-The user question "which tickets are waiting on the customer?" becomes one ability invocation with `status: "waiting_customer"`. The agent doesn't scan a list of 8 near-identical tool names; it scans one, and the enum documents what values are valid.
-
-The same plugin also registers a zero-arg `myplugin-tickets/get-queue-summary` ability (open count + average response time + oldest unresolved) because "how is the queue today?" is the highest-frequency support-team question and the backing endpoint takes no arguments. That one ability has outsized value for one line of registration code — rule 4 in action.
-
-## Escape hatch — when per-operation granularity is right (for reads)
-
-Two cases where one-ability-per-operation IS appropriate on the read
-side, despite the recommendation against REST-atomization for reads:
-
-1. **Genuinely different permission models.** If `list-<resource>` and `search-<resource>` require different capabilities or different confirmation flows, splitting is honest.
-2. **Different destructive / idempotent annotations.** An ability that both reads and writes cannot honestly declare `readonly: true`; split the read-only part into its own ability.
-
-For writes, this escape hatch isn't needed: rule 2 ("one state
-transition per ability") already establishes per-operation granularity
-as the default. Splitting `submit-evidence` and `close-resource` into
-separate abilities isn't an exception — it's rule 2 in action.
-
-## Related references
-
-- `domain-vs-projection.md` — granularity governs *domain-layer* decisions; that reference covers the projection layer where token-efficiency tradeoffs and consumer-shape choices live.
-- `shared-core-service.md` — implementation mechanism for keeping abilities, REST handlers, CLI commands, and UI in lockstep on the domain layer.