Add execute actions to the ability object (#56)

* Add execute actions to the ability object

* Update includes/abilities-api/class-wp-ability.php

Co-authored-by: Dovid Levine <[email protected]>

* Add WordPress actions for ability execution hooks

- Add before_execute_ability action that fires before ability execution
- Add after_execute_ability action that fires after successful execution
- Include comprehensive unit tests for both actions with edge cases
- Add extensibility documentation with usage examples and best practices
- Update README with new documentation link
- Fix PHPDoc formatting for action parameters

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Improve code quality

* Update README.md

Co-authored-by: Dovid Levine <[email protected]>

* Address feedback from review

---------

Co-authored-by: Dovid Levine <[email protected]>
Co-authored-by: Claude <[email protected]>

Co-authored-by: gziolo <[email protected]>
Co-authored-by: justlevine <[email protected]>
Co-authored-by: jonathanbossenger <[email protected]>

Author: 3 people

README.md

@@ -23,6 +23,7 @@
 - [Registering Abilities](docs/3.registering-abilities.md)
 - [Using Abilities](docs/4.using-abilities.md)
 - [REST API Reference](docs/5.rest-api.md)
+- [Hooks](docs/6.hooks.md)
 - [Contributing Guidelines](CONTRIBUTING.md)
 
 ## Inspiration
@@ -36,16 +37,16 @@
 | Milestone                           | State       |
 | ----------------------------------- | ----------- |
 | Placeholder repository              | **created** |
-| Spec draft                          | in progress |
-| Prototype plugin & Composer package | in progress |
-| Community feedback (#core‑ai Slack) | planned     |
+| Spec draft                          | **created** |
+| Prototype plugin & Composer package | **created** |
+| Community feedback (#core‑ai Slack) | in progress |
 | Core proposal                       | planned     |
 
 ## How to Get Involved
 
 - **Discuss:** `#core-ai` channel on WordPress Slack.
 - **File issues:** suggestions & use‑cases welcome in this repo.
-- **Prototype:** experiment with the upcoming Composer package once released.
+- **Prototype:** experiment with the [feature plugin](https://github.com/WordPress/abilities-api/releases/latest) or the [`wordpress/abilities-api`](https://packagist.org/packages/wordpress/abilities-api) Composer package.
 
 ## License
 

docs/6.hooks.md

@@ -0,0 +1,68 @@
+# 6. Hooks
+
+The Abilities API provides [WordPress Action Hooks](https://developer.wordpress.org/apis/hooks/) that allow developers to monitor and respond to ability execution events.
+
+## Available Actions
+
+### `before_execute_ability`
+
+Fires immediately before an ability gets executed, after permission checks have passed but before the execution callback is called.
+
+```php
+/**
+ * Fires before an ability gets executed.
+ *
+ * @since n.e.x.t
+ *
+ * @param string $ability_name The name of the ability.
+ * @param mixed  $input        The input data for the ability.
+ */
+do_action( 'before_execute_ability', $ability_name, $input );
+```
+
+**Parameters:**
+
+- `$ability_name` (`string`): The namespaced name of the ability being executed (e.g., `my-plugin/get-posts`).
+- `$input` (`mixed`): The input data passed to the ability.
+
+### `after_execute_ability`
+
+Fires immediately after an ability has finished executing successfully, after output validation has passed.
+
+```php
+/**
+ * Fires immediately after an ability finished executing.
+ *
+ * @since n.e.x.t
+ *
+ * @param string $ability_name The name of the ability.
+ * @param mixed  $input        The input data for the ability.
+ * @param mixed  $result       The result of the ability execution.
+ */
+do_action( 'after_execute_ability', $ability_name, $input, $result );
+```
+
+**Parameters:**
+
+- `$ability_name` (`string`): The namespaced name of the ability that was executed.
+- `$input` (`mixed`): The input data that was passed to the ability.
+- `$result` (`mixed`): The validated result returned by the ability's execution callback.
+
+## Usage Examples
+
+**Basic Logging**
+
+```php
+// Log all ability executions.
+add_action( 'before_execute_ability', function( $ability_name, $input ) {
+    error_log( 'Executing ability: ' . $ability_name );
+    if ( $input !== null ) {
+        error_log( 'Input: ' . wp_json_encode( $input ) );
+    }
+}, 10, 2 );
+
+add_action( 'after_execute_ability', function( $ability_name, $input, $result ) {
+    error_log( 'Completed ability: ' . $ability_name );
+    error_log( 'Result: ' . wp_json_encode( $result ) );
+}, 10, 3 );
+```

includes/abilities-api.php

@@ -7,8 +7,6 @@
  * @package WordPress
  * @subpackage Abilities_API
  * @since 0.1.0
- *
- * phpcs:disable WordPress.NamingConventions.PrefixAllGlobals
  */
 
 declare( strict_types = 1 );

includes/abilities-api/class-wp-ability.php

@@ -416,14 +416,38 @@ public function execute( $input = null ) {
 			);
 		}
 
+		/**
+		 * Fires before an ability gets executed.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param string $ability_name The name of the ability.
+		 * @param mixed  $input        The input data for the ability.
+		 */
+		do_action( 'before_execute_ability', $this->name, $input );
+
 		$result = $this->do_execute( $input );
 		if ( is_wp_error( $result ) ) {
 			return $result;
 		}
 
 		$is_valid = $this->validate_output( $result );
+		if ( is_wp_error( $is_valid ) ) {
+			return $is_valid;
+		}
 
-		return is_wp_error( $is_valid ) ? $is_valid : $result;
+		/**
+		 * Fires immediately after an ability finished executing.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param string $ability_name The name of the ability.
+		 * @param mixed  $input        The input data for the ability.
+		 * @param mixed  $result       The result of the ability execution.
+		 */
+		do_action( 'after_execute_ability', $this->name, $input, $result );
+
+		return $result;
 	}
 
 	/**

phpcs.xml.dist

@@ -193,11 +193,10 @@
 
 	<!-- Plugin-specific rule configs  -->
 	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
+		<exclude-pattern>includes/abilities-api.php</exclude-pattern>
+		<exclude-pattern>includes/abilities-api/*</exclude-pattern>
 		<properties>
 			<property name="prefixes" type="array">
-				<element value="abilities_api_" /><!-- Hook prefix -->
-				<element value="WP_Ability" />
-				<element value="WP_Abilities" />
 				<element value="WP_REST_Abilities" />
 				<element value="WP_ABILITIES_API" /><!-- Constant -->
 			</property>