wordpress-agent-kit 0.3.0 → 0.4.0

package/.github/skills/wp-abilities-api/references/input-schema-gotchas.md

@@ -0,0 +1,265 @@
+# Input schema gotchas
+
+Three surprises the Abilities API's `input_schema` will ship with if you rely on schema declarations alone. All three have been caught in real plugin work after the schema looked correct and tests passed; each has a defensive pattern that makes the execute callback robust regardless.
+
+## 1. Schema `default` values are NOT injected into execute callback input
+
+### Problem
+
+`wp_register_ability()` lets you declare per-property defaults in `input_schema`:
+
+```php
+'input_schema' => [
+    'type'       => 'object',
+    'properties' => [
+        'submit' => [
+            'type'        => 'boolean',
+            'default'     => false,
+            'description' => __( 'Whether to submit evidence for review.', '<text-domain>' ),
+        ],
+    ],
+],
+```
+
+The Abilities API's validate path enforces `type` and `required`, but it does NOT populate missing properties with their declared `default`. If an agent invokes the ability with `{ dispute_id: "dp_..." }` and omits `submit`, the execute callback receives `$input` **without** a `submit` key — it does not get `$input['submit'] = false`.
+
+### Symptoms
+
+- Boolean defaults silently become "undefined" in the callback and any `if ( $input['submit'] )` check compares against `null`, which works by accident but fails `isset` checks and strict-type branches.
+- Integer pagination defaults like `'page' => [ 'default' => 1 ]` never reach the backing controller, so pagination falls back to the controller's internal default rather than the one declared in the schema.
+- Object defaults (`'metadata' => [ 'default' => [] ]`) become `null` rather than `[]` and any `foreach ( $input['metadata'] as ... )` hits a type error.
+
+### Fix — normalize defaults explicitly in the execute callback
+
+```php
+public static function execute_submit_evidence( $input = null ) {
+    if ( ! is_array( $input ) ) {
+        $input = [];
+    }
+
+    // Apply schema defaults the Abilities API does not inject.
+    if ( ! array_key_exists( 'submit', $input ) || null === $input['submit'] ) {
+        $input['submit'] = false;
+    }
+    $input['submit'] = (bool) $input['submit'];
+
+    if ( ! array_key_exists( 'metadata', $input ) || null === $input['metadata'] ) {
+        $input['metadata'] = [];
+    }
+
+    // ... rest of callback
+}
+```
+
+The `array_key_exists` + null-check pattern catches both "missing key" and "explicit null" (some serializers produce nulls for optional fields).
+
+Keep the declared `default` in `input_schema` anyway — it documents the expected behavior for anyone reading the registration and is visible to agents in the schema introspection endpoints. Just don't rely on it for runtime population.
+
+## 2. Pagination parameter-name drift
+
+### Problem
+
+The `input_schema` convention across most WordPress REST endpoints is `per_page` (matching WP core REST list endpoints and `WP_REST_Controller`'s `get_collection_params()`). Some plugin REST controllers, however, delegate to an internal request-builder class that reads a different key (e.g. `pagesize` or `page_size`), typically for historical reasons.
+
+If the ability's `input_schema` exposes `per_page` and the backing controller reads `pagesize`, the agent's `per_page: 50` silently never reaches pagination — the value is accepted, forwarded verbatim to the backing, and then ignored. Agents keep getting the default page size and suspect their filter is broken.
+
+### Symptoms
+
+- List abilities return the backing controller's default page size regardless of the agent's `per_page` input.
+- Integration tests that only check "a list came back" pass; only a test asserting `count( $response['data'] )` catches it.
+- Harness runs show the raw response count matching the default (25, 10, etc.) for every call.
+
+### Detection heuristic
+
+Before shipping a paginated ability, grep the backing controller's call chain:
+
+```bash
+# Check the backing controller and anything it delegates to.
+grep -rn "pagesize\|page_size" <path/to/backing-controller.php> <path/to/request-helpers/>
+```
+
+If `pagesize` (or any non-`per_page` key) appears in the chain and the ability's schema exposes `per_page`, the execute callback MUST translate.
+
+### Fix — translate before delegating
+
+```php
+/**
+ * Translate pagination keys for abilities whose backing reads a non-standard key.
+ *
+ * Abilities expose `per_page` uniformly for agent-facing consistency; this
+ * helper rewrites it to whatever key the backing actually reads.
+ *
+ * @param array|null $input Ability input (or null).
+ * @return array|null       Input with `per_page` rewritten to `<backing_key>` when present.
+ */
+private static function translate_pagination_keys( $input ) {
+    if ( ! is_array( $input ) ) {
+        return $input;
+    }
+    if ( isset( $input['per_page'] ) ) {
+        $input['<backing_key>'] = $input['per_page'];
+        unset( $input['per_page'] );
+    }
+    return $input;
+}
+
+public static function execute_get_things( $input = null ) {
+    $input = self::translate_pagination_keys( is_array( $input ) ? $input : null );
+
+    return self::delegate_to_rest_controller(
+        '<Backing_Controller_Class>',
+        'get_things',
+        '/my-plugin/v1/things',
+        $input
+    );
+}
+```
+
+Place the translation BEFORE the delegate call so `per_page` never reaches the backing.
+
+### When NOT to apply this
+
+Do not apply blindly. If the backing reads `per_page` directly (most modern WP REST controllers do), adding this translation would silently break pagination by renaming the key to something the backing doesn't understand.
+
+**Always grep the backing first.** The translation is only correct for a specific backing chain; it's not a general safety net.
+
+## 3. ID validation must not use `empty()`
+
+### Problem
+
+PHP's `empty()` is permissive in ways that bite ID validation:
+
+```php
+empty( '0' )   // true  — but "0" is a legal string ID (order ID, row ID, post ID in some code paths)
+empty( 0 )     // true  — same for integer zero
+empty( [] )    // true  — expected, but same keyword used for different cases
+```
+
+An execute callback that guards required IDs with `empty( $input['order_id'] )` will false-reject a legitimate `"0"` and return a "missing" error for input that's actually present. The agent retries with the same input, gets the same error, and the call is stuck.
+
+### Symptoms
+
+- Abilities reject specific IDs ending in zero or consisting of zero.
+- Unit tests written with non-zero IDs pass; a regression lands the day an agent tries a real zero-ID.
+- `WP_Error( '<plugin>_missing_<field>' )` fires for input the schema validator would have accepted.
+
+### Fix — three explicit checks
+
+```php
+if ( ! isset( $input['order_id'] )
+    || ! is_string( $input['order_id'] )
+    || '' === $input['order_id']
+) {
+    return new \WP_Error(
+        '<plugin>_missing_order_id',
+        __( 'An order_id is required to fetch order detail.', '<text-domain>' )
+    );
+}
+```
+
+Three separate checks, each non-redundant:
+
+1. `! isset( ... )` — the key is present on the array.
+2. `! is_string( ... )` — type is right. (For integer IDs, use `is_int` + non-negative check instead.) Without this, a caller that passes `123` (integer) where the schema documents a string would fall through to a later step that does `rawurlencode( $input['order_id'] )` and produces a cryptic coercion error rather than a clean missing-field response.
+3. `'' === $input[ ... ]` — non-empty in the strict sense. Rejects empty string only; accepts `"0"` as a legal value.
+
+Use the standardized `<plugin>_missing_<field>` error code (see `error-code-vocabulary.md`) for this case.
+
+### Add a regression-guard unit test
+
+The guard is load-bearing enough that it deserves an explicit test — otherwise someone will simplify it back to `empty()` in a future refactor:
+
+```php
+public function test_execute_returns_wp_error_when_id_not_a_string() {
+    $result = My_Plugin_Abilities::execute_get_thing( [ 'order_id' => 123 ] );
+    $this->assertInstanceOf( \WP_Error::class, $result );
+    $this->assertSame( '<plugin>_missing_order_id', $result->get_error_code() );
+}
+```
+
+The integer `123` is a fine canary — it's non-empty, it `isset`s, but it's not a string. A callback that only uses `isset` + `empty` would false-pass this input and fall through to the URL construction with an integer argument.
+
+## 4. Direct vs indirect invocation differ in strictness
+
+### Problem
+
+Two ways exist to invoke an ability's `execute_callback`:
+
+- **Direct.** A caller imports the registrar and calls the static method (`Abilities_Registrar::execute_get_things( $input )`). PHP signature defaults apply; no schema validation runs.
+- **Indirect.** A caller resolves the ability through `wp_get_ability( '<id>' )->execute( $input )`. WordPress runs `WP_Ability::normalize_input()` then `validate_input()` (then `check_permissions()`) before the callback is invoked.
+
+The two paths differ in three ways agents trip over:
+
+1. **Validation against `input_schema` runs only on the indirect path.** If the ability declares an object-typed schema with properties and the indirect caller passes `null` (or omits the argument entirely, as `$ability->execute()` does), `validate_input()` rejects with an `ability_invalid_input` error before the callback runs. The PHP-level `$input = null` default in the callback signature is dead code on this path.
+
+2. **Schema's top-level `default` IS applied — but only on the indirect path.** `normalize_input()` substitutes the schema's top-level `default` when the caller passes `null`. Direct callers don't run through this method; they get whatever PHP default the callback signature declares. Declaring `default => (object) array()` at the schema root makes `$ability->execute()` work without arguments — but the same callback called directly still receives PHP `null`.
+
+3. **The callback's first argument arrives only when `input_schema` is non-empty.** WordPress only forwards `$input` to the callback when the schema is declared. Without an input schema, the callback is invoked with zero arguments — PHP-level signature defaults compensate for this if you wrote them; without them, the indirect path produces an `ArgumentCountError`.
+
+### Symptoms
+
+- An ability looks fine when unit-tested by directly invoking the static method, then fails the moment it's exercised through `wp_get_ability(...)->execute()` from MCP / Command Palette / agent harnesses.
+- "Works in the test, breaks in MCP" — typical pattern when a test calls `Abilities_Registrar::execute_get_things( [] )` (passing an empty array) but the agent invocation goes through the indirect pipeline.
+- A schema with all-optional properties still rejects zero-arg indirect calls because `null` is not an object.
+
+### Fix — declare a top-level schema `default` for any zero-arg-allowed ability
+
+```php
+'input_schema' => [
+    'type'       => 'object',
+    'default'    => (object) array(),  // applied by normalize_input() on null inputs
+    'properties' => [
+        'per_page' => [ 'type' => 'integer', 'default' => 10 ],
+        // ...
+    ],
+],
+```
+
+`(object) array()` is preferred over `[]` because it json-encodes to `{}` rather than the array literal `[]`, avoiding PHP's array/object ambiguity at the validator boundary.
+
+### Distinguish from Gotcha 1
+
+Top-level schema `default` is honored by `normalize_input()` and reaches the callback. Property-level `default` (Gotcha 1) is NOT — those values are dropped by the validator, and the callback has to defensively reapply them. Different layers, different fates.
+
+If you've declared the top-level `default` in the schema, the PHP-level signature default exists only for direct callers. Don't add a third layer of fallback inside the callback that re-checks `if ( $input === null )` — three compensating defaults stacked on each other diffuses the meaning of "no input."
+
+## Putting gotchas 1-3 together
+
+A hardened execute callback for a list-style ability with a required ID, schema defaults, and backing pagination drift:
+
+```php
+public static function execute_get_thing_details( $input = null ) {
+    if ( ! is_array( $input ) ) {
+        $input = [];
+    }
+
+    // Gotcha 3: required-ID validation (not empty()).
+    if ( ! isset( $input['thing_id'] )
+        || ! is_string( $input['thing_id'] )
+        || '' === $input['thing_id']
+    ) {
+        return new \WP_Error(
+            '<plugin>_missing_thing_id',
+            __( 'A thing_id is required.', '<text-domain>' )
+        );
+    }
+
+    // Gotcha 1: apply defaults the Abilities API doesn't inject.
+    if ( ! array_key_exists( 'include_history', $input ) || null === $input['include_history'] ) {
+        $input['include_history'] = false;
+    }
+    $input['include_history'] = (bool) $input['include_history'];
+
+    // Gotcha 2: translate pagination before delegating (only if backing reads a non-standard key).
+    $input = self::translate_pagination_keys( $input );
+
+    return self::delegate_to_rest_controller(
+        '<Backing_Controller_Class>',
+        'get_thing',
+        '/my-plugin/v1/things/' . rawurlencode( $input['thing_id'] ),
+        $input
+    );
+}
+```
+
+Each of the three lines the callback adds on top of the "just delegate" pattern has a paid-for bug behind it. Keep them.

package/.github/skills/wp-abilities-api/references/php-registration.md

@@ -25,11 +25,22 @@ add_action( 'wp_abilities_api_categories_init', function() {
 // 2. Then register abilities
 add_action( 'wp_abilities_api_init', function() {
     wp_register_ability( 'my-plugin/get-info', [
-        'label'       => __( 'Get Site Info', 'my-plugin' ),
-        'description' => __( 'Returns basic site information.', 'my-plugin' ),
-        'category'    => 'my-plugin',
-        'callback'    => 'my_plugin_get_info_callback',
-        'meta'        => [ 'show_in_rest' => true ],
+        'label'               => __( 'Get Site Info', 'my-plugin' ),
+        'description'         => __( 'Returns basic site information.', 'my-plugin' ),
+        'category'            => 'my-plugin',
+        'execute_callback'    => 'my_plugin_get_info_callback',
+        'permission_callback' => 'my_plugin_get_info_permissions',
+        'meta'                => [
+            'show_in_rest' => true,
+            'mcp'          => [
+                'public' => true, // Expose via the bundled WordPress MCP adapter.
+            ],
+            'annotations'  => [
+                'readonly'    => true,
+                'destructive' => false,
+                'idempotent'  => true,
+            ],
+        ],
     ] );
 } );
 ```
@@ -41,27 +52,43 @@ add_action( 'wp_abilities_api_init', function() {
 
 ## Key arguments for `wp_register_ability()`
 
-| Argument | Description |
-|----------|-------------|
-| `label` | Human-readable name for UI (e.g., command palette) |
-| `description` | What the ability does |
-| `category` | Category ID (must be registered first) |
-| `callback` | Function that executes the ability |
-| `input_schema` | JSON Schema for expected input (enables validation) |
-| `output_schema` | JSON Schema for returned output |
-| `permission_callback` | Optional function to check if current user can execute |
-| `meta.show_in_rest` | Set `true` to expose via REST API |
-| `meta.readonly` | Set `true` if ability is informational only |
+| Argument | Required? | Description |
+|----------|-----------|-------------|
+| `label` | **Required** | Human-readable name for UI (e.g., command palette). |
+| `description` | **Required** | What the ability does. |
+| `category` | **Required** | Category ID (must be registered first via `wp_abilities_api_categories_init`). |
+| `execute_callback` | **Required** | Function that runs when the ability is invoked. Receives mixed input (per `input_schema`), returns mixed result or `WP_Error`. |
+| `permission_callback` | **Required** | Function that checks whether the current user may execute. Receives the same mixed input as `execute_callback`; returns `bool` or `WP_Error`. WP core throws `InvalidArgumentException` if this is missing — there is no implicit default. |
+| `input_schema` | Optional | JSON Schema for expected input (enables validation). Required when the ability accepts input. |
+| `output_schema` | Optional | JSON Schema for returned output (enables validation of the result). |
+| `meta.show_in_rest` | Optional (default `false`) | Set `true` to expose via the `wp-abilities/v1` REST API namespace. |
+| `meta.mcp.public` | Optional (default `false`) | Set `true` to expose the ability as a tool via the bundled WordPress MCP adapter. Independent from `show_in_rest`. |
+| `meta.mcp.type` | Optional (default `'tool'`) | One of `'tool'`, `'resource'`, `'prompt'`. Controls how the bundled MCP adapter projects the ability. Values outside this enum silently coerce to `'tool'`. |
+| `meta.annotations.readonly` | **Strongly recommended** (default `null`) | `true` if the ability does not modify its environment. |
+| `meta.annotations.destructive` | **Strongly recommended** (default `null`) | `true` if the ability may perform destructive updates. `false` for additive-only updates. |
+| `meta.annotations.idempotent` | **Strongly recommended** (default `null`) | `true` if calling the ability repeatedly with the same arguments has no additional effect. |
+
+The three annotations under `meta.annotations` are *hints* for tooling and documentation — core does not enforce them at runtime, so a missing or `null` value is silently legal. That permissiveness is exactly why every registration should populate them explicitly: MCP / Command Palette / agent surfaces and review tooling reason about ability safety from these values *without* invoking the callback. A `readonly: null` ability is treated as "behavior unknown," which is a worse signal than either `true` or `false`. Treat the absence of an annotation as a bug, not a default.
+
+### `show_in_rest` vs `mcp.public` — they target different surfaces
+
+These two meta keys answer different questions and do not imply each other:
+
+- `show_in_rest` controls visibility on the WordPress core REST namespace `wp-abilities/v1` (the abilities REST API). Clients that talk to that namespace see the ability iff this is `true`.
+- `mcp.public` is read by the bundled WordPress MCP adapter package. The adapter's default MCP server only surfaces abilities whose `meta.mcp.public` is strictly `true`. Without it, the ability is registered but invisible to MCP clients connecting through that adapter.
+
+A plugin can set both, either, or neither. If you want the ability discoverable to agents through MCP, set `mcp.public => true`. If you also want it on the abilities REST namespace (for tooling that talks to `wp-abilities/v1` directly), set `show_in_rest => true`. The two surfaces are independent.
 
 ## Recommended patterns
 
-- Namespace IDs (e.g. `my-plugin:feature.edit`).
-- Treat IDs as stable API; changing IDs is a breaking change.
+- Namespace ability IDs as `<plugin-slug>/<verb-noun>` (e.g., `my-plugin/get-info`, `my-plugin/update-thing`). Slash-separated.
+- Treat IDs as stable API; changing an ID is a breaking change for any consumer that holds a reference.
 - Use `input_schema` and `output_schema` for validation and to help AI agents understand usage.
-- Always include a `permission_callback` for abilities that modify data.
+- **Always include a `permission_callback`.** It is required on every registration — there is no implicit default.
+- **Always set all three `meta.annotations` keys (`readonly`, `destructive`, `idempotent`) explicitly.** Leaving them at the `null` default broadcasts "behavior unknown" to every consumer that reads this metadata before invoking the ability. The cost of writing them is three lines; the cost of omitting them is opaque safety surface.
 
 ## References
 
 - Abilities API handbook: https://developer.wordpress.org/apis/abilities-api/
 - Dev note: https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/
-
+- WordPress MCP adapter package — source of `meta.mcp.public` / `meta.mcp.type` contract. The adapter ships as a packaged dependency; verify the meta-key names against the package version your plugin pulls in.

package/.github/skills/wp-abilities-api/references/plugin-family-patterns.md

@@ -0,0 +1,233 @@
+# Plugin-family patterns
+
+This reference covers shared implementation *mechanics* — the call shape your execute callbacks follow when handing work to existing business logic. Two shapes are common enough across real-world WordPress plugins to be worth naming; which one fits is determined by how the backing controller is constructed, not by a choice you make up front. The choice still ripples through your delegate helper, your tests, and your error codes, so it's worth confirming early.
+
+Family-specific *registration* conventions — loader path, ability category, MCP exposure defaults, error-code prefix house style — live in separate plugin-family overlays (for example, a WooCommerce-extension overlay), not in this reference. Apply any relevant overlay before scaffolding registration. The patterns below should stay portable: they describe how the execute callback talks to backing code, not what the registration metadata should look like for your plugin family.
+
+There is also a third option that sits *outside* this dichotomy. If the operation does not yet have a shared service class — or if you can refactor toward one — extracting a service that the ability, the REST controller, and the UI all consume is the default per `shared-core-service.md`. Delegation through an existing REST controller (either shape below) is a conditional shortcut for low-stakes reads, not the starting point. Confirm the shape is right before you reach for either.
+
+## Shape: shared API client
+
+Common in plugins that talk to a remote service (Stripe, a first-party SaaS, an upstream API). The plugin bootstraps a single API client, exposes it via a static accessor on a main plugin class, and every REST controller takes that client as a constructor argument.
+
+### Detection
+
+```bash
+# Inspect the backing REST controller's __construct signature.
+grep -n "public function __construct" <path/to/rest-controller.php>
+```
+
+If the constructor takes a required typed argument (e.g. `My_Plugin_API_Client $api_client`), you're in the shared-API-client shape. Confirm the plugin has a central accessor:
+
+```bash
+grep -rn "get_api_client\|get_.*_api_client\|get_service" <path/to/plugin/main-class.php>
+```
+
+You're looking for a `public static function get_<something>()` that returns the shared client.
+
+### Minimal skeleton
+
+```php
+<?php
+namespace My_Plugin\Abilities;
+
+class Abilities_Registrar {
+
+    const CATEGORY_SLUG = 'my-plugin';
+
+    public static function init() {
+        add_action( 'wp_abilities_api_categories_init', [ __CLASS__, 'register_category' ] );
+        add_action( 'wp_abilities_api_init', [ __CLASS__, 'register_abilities' ] );
+    }
+
+    public static function register_abilities() {
+        wp_register_ability(
+            'my-plugin/get-things',
+            [
+                'label'               => __( 'Get things', 'my-plugin' ),
+                'description'         => __( 'List things with filters.', 'my-plugin' ),
+                'category'            => self::CATEGORY_SLUG,
+                'input_schema'        => [ /* ... */ ],
+                'execute_callback'    => [ __CLASS__, 'execute_get_things' ],
+                'permission_callback' => [ __CLASS__, 'current_user_has_capability' ],
+                'meta'                => [
+                    'annotations'  => [ 'readonly' => true, 'destructive' => false, 'idempotent' => true ],
+                    'show_in_rest' => true,
+                ],
+            ]
+        );
+    }
+
+    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
+        );
+    }
+
+    private static function delegate_to_rest_controller( $controller_class, $method, $route, $input, $http_method = 'GET' ) {
+        $fqcn = '\\' . $controller_class;
+        if ( ! class_exists( $fqcn ) ) {
+            return new \WP_Error( 'my_plugin_not_initialized', __( 'My Plugin is not initialized.', 'my-plugin' ) );
+        }
+
+        // Shape specifics: fetch the shared API client and null-check.
+        $api_client = null;
+        if ( class_exists( '\My_Plugin' ) && method_exists( '\My_Plugin', 'get_api_client' ) ) {
+            $api_client = \My_Plugin::get_api_client();
+        }
+        if ( null === $api_client ) {
+            return new \WP_Error( 'my_plugin_not_initialized', __( 'My Plugin is not initialized.', 'my-plugin' ) );
+        }
+
+        $request = new \WP_REST_Request( $http_method, $route );
+        if ( is_array( $input ) ) {
+            foreach ( $input as $param => $value ) {
+                $request->set_param( $param, $value );
+            }
+        }
+
+        $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 : [];
+    }
+}
+```
+
+### Testing implications
+
+- **Bootstrap test doubles need the API client.** Unit tests that instantiate controllers must provide a mocked or stubbed client; otherwise the constructor fails with `ArgumentCountError: Too few arguments`.
+- **The "not initialized" error path is reachable and must be covered.** One unit test should stub the accessor to return null and assert the ability returns `<plugin>_not_initialized`. This is a common failure during partial bootstraps (WP-CLI with restricted loading, test harnesses, admin pages with conditional autoloading).
+- **Integration tests need real or faked HTTP.** The backing controller will hit the upstream unless the API client is mocked, so integration harnesses typically route through a fake transport.
+
+Worked example: a plugin that talks to an external SaaS or upstream HTTP service typically follows this pattern. The plugin's main class exposes the API client via a static accessor (e.g. `Plugin_Main::get_api_client()`); REST controllers extend a base class whose constructor takes that client as a typed argument; the abilities registrar pulls the client through the same accessor before constructing controllers.
+
+## Shape: zero-arg controllers
+
+Common in plugins/packages that delegate primarily to WordPress core mechanisms (custom post types, options, meta) and don't maintain a single shared API client. Controllers instantiate cleanly without a dependency graph.
+
+### Detection
+
+```bash
+grep -n "public function __construct" <path/to/rest-controller.php>
+```
+
+If the constructor takes no required arguments, or takes only simple scalars you can hardcode at the ability call site (e.g. a post-type string), you're in the zero-arg shape.
+
+Also grep the plugin's main bootstrap class for the absence of a singleton API accessor — if there isn't one, the zero-arg shape is the honest choice.
+
+### Minimal skeleton
+
+```php
+<?php
+namespace My_Plugin\Abilities;
+
+class Abilities_Registrar {
+
+    const CATEGORY_SLUG = 'my-plugin';
+
+    public static function init() {
+        add_action( 'wp_abilities_api_categories_init', [ __CLASS__, 'register_category' ] );
+        add_action( 'wp_abilities_api_init', [ __CLASS__, 'register_abilities' ] );
+    }
+
+    public static function register_abilities() {
+        wp_register_ability(
+            'my-plugin/get-things',
+            [
+                /* ... */
+                'execute_callback' => [ __CLASS__, 'execute_get_things' ],
+                /* ... */
+            ]
+        );
+    }
+
+    public static function execute_get_things( $input = null ) {
+        $input    = is_array( $input ) ? $input : [];
+        $endpoint = new \My_Plugin_Things_Endpoint();
+        $request  = new \WP_REST_Request( 'GET', '/my-plugin/v1/things' );
+
+        foreach ( [ 'page', 'per_page', 'status', 'search' ] as $key ) {
+            if ( isset( $input[ $key ] ) ) {
+                $request->set_param( $key, $input[ $key ] );
+            }
+        }
+
+        $response = $endpoint->get_items( $request );
+        if ( is_wp_error( $response ) ) {
+            return $response;
+        }
+        return $response instanceof \WP_REST_Response ? $response->get_data() : $response;
+    }
+}
+```
+
+No helper is required — the construction step is a single line and inlining per callback stays readable. If you do extract a helper, it takes a `constructor_args` parameter because the controller class isn't constant across abilities:
+
+```php
+/**
+ * @param string     $controller_class Fully-qualified controller class.
+ * @param string     $method           Method to invoke on the request.
+ * @param string     $route            REST route used when constructing WP_REST_Request.
+ * @param array|null $input            Ability input (or null).
+ * @param string     $http_method      HTTP method. Defaults to 'GET'.
+ * @param array      $constructor_args Optional scalar args for the controller's constructor.
+ * @return array|\WP_Error
+ */
+private static function delegate_to_rest_controller(
+    $controller_class,
+    $method,
+    $route,
+    $input,
+    $http_method = 'GET',
+    $constructor_args = array()
+) {
+    /* ... */
+}
+```
+
+The phpDoc carries the `array|\WP_Error` return shape; the function signature itself stays untyped on the return so this snippet parses on PHP 7.2+.
+
+See `delegate-helper-pattern.md` for the full helper signature and guards.
+
+### Testing implications
+
+- **No API-client mock needed.** Unit tests instantiate the ability registrar directly and call `execute_*` with input arrays.
+- **Test at the `wp_get_ability()` level when possible.** With zero-arg controllers the backing often exists in WordPress core territory (e.g. custom post types), so integration tests can exercise the full pipeline without a fake transport.
+- **The `<plugin>_not_initialized` failure mode is less common.** It still exists — if a package isn't loaded, `class_exists` on the backing controller still fails — but the surface area is smaller.
+
+Worked example: a plugin whose REST controllers wrap a custom post type, taxonomy, option, or meta typically follows this pattern. Each execute callback constructs its controller inline (e.g. `new My_CPT_Endpoint( 'my_cpt' )`), passing whatever scalar (post-type slug, taxonomy name) the controller needs. No shared helper in the registrar; the construction step is small enough to inline.
+
+## Hybrid cases
+
+A single plugin can legitimately use both patterns across different abilities:
+
+- A shared-API-client ability for backing controllers that talk to the upstream service.
+- A zero-arg ability for backing controllers that only touch WP core (e.g. a CPT-based settings endpoint in the same plugin).
+
+If this happens, the helper in `delegate-helper-pattern.md` can support both via optional `constructor_args` — but resist the temptation to over-engineer until you have at least two zero-arg abilities that would share the helper.
+
+## Anti-pattern — inventing an API client where there isn't one
+
+Don't introduce a fake shared API client to fit the shared-client helper shape. If the plugin is genuinely stateless / CPT-driven, inline construction is the honest answer. The helper is scaffolding that pays back when you have 4+ abilities sharing the build-request → instantiate → unwrap flow; before that, inline code is faster to read and review.
+
+## Picking quickly
+
+| Signal | Likely pattern |
+|---|---|
+| Backing controller's `__construct` takes an API-client-like object | A |
+| Plugin has a `Plugin::get_*_client()` static accessor | A |
+| Plugin talks to an external SaaS / upstream HTTP service | A |
+| Backing controller `__construct` is zero-arg or only takes scalars | B |
+| Backing is a CPT / options / meta wrapper | B |
+| Plugin's REST surface wraps WP-core post types, taxonomies, options, or meta | B |