Fix factual errors in Claude skills and agents (#3370)

Author: pfefferle

.agents/skills/code-style/SKILL.md

@@ -87,7 +87,7 @@ class Custom extends Base {
 **Examples:**
 - `includes/transformer/class-post.php` - Post transformation.
 - `includes/transformer/class-comment.php` - Comment transformation.
-- `includes/transformer/class-event.php` - Event-specific transformation.
+- `includes/transformer/class-user.php` - User/actor transformation.
 
 ### Handlers
 Process incoming ActivityPub activities from remote servers.
@@ -137,11 +137,8 @@ $content = enrich_content_data( $content, $pattern, $callback );
 // Resolve WebFinger handle to actor URL.
 $resource = Webfinger::resolve( $handle );
 
-// Get user's ActivityPub actor URL.
-$actor_url = get_author_posts_url( $user_id );
-
-// Check if a post type is enabled for ActivityPub.
-$enabled = \is_post_type_enabled( $post_type );
+// Check whether a post is disabled for ActivityPub (the federation pipeline gate).
+$disabled = is_post_disabled( $post );
 ```
 
 ## Real Codebase Examples
@@ -153,14 +150,14 @@ $enabled = \is_post_type_enabled( $post_type );
 - `includes/class-signature.php` - HTTP Signatures for federation.
 
 **Activity Types:**
-- `includes/activity/class-activity.php` - Base activity class.
-- `includes/activity/class-follow.php` - Follow activity.
-- `includes/activity/class-undo.php` - Undo activity.
+- `includes/activity/class-activity.php` - Activity class (Create, Follow, Undo, etc. are built from this).
+- `includes/activity/class-base-object.php` - Base object class.
+- `includes/activity/extended-object/` - Extended object types (e.g. Event).
 
 **Integrations (see [Integration Patterns](../integrations/SKILL.md)):**
-- `integration/class-woocommerce.php` - WooCommerce integration.
 - `integration/class-buddypress.php` - BuddyPress integration.
 - `integration/class-jetpack.php` - Jetpack integration.
+- `integration/class-opengraph.php` - OpenGraph integration.
 
 ## Common Initialization Patterns
 
@@ -172,7 +169,7 @@ class Feature {
      */
     public static function init() {
         \add_action( 'init', array( self::class, 'register' ) );
-        \add_filter( 'activitypub_activity_object', array( self::class, 'filter' ) );
+        \add_filter( 'activitypub_the_content', array( self::class, 'filter' ) );
     }
 }
 ```
@@ -199,16 +196,15 @@ class Manager {
 
 **Actions:**
 ```php
-\do_action( 'activitypub_before_send_activity', $activity );
-\do_action( 'activitypub_after_send_activity', $activity, $response );
-\do_action( 'activitypub_inbox_received', $activity );
+\do_action( 'activitypub_handled_create', $activity, $user_ids, $success, $result );
+\do_action( 'activitypub_followers_pre_remove_follower', $follower, $user_id, $actor );
 ```
 
 **Filters:**
 ```php
-$activity = \apply_filters( 'activitypub_activity_object', $activity, $post );
+$array   = \apply_filters( 'activitypub_activity_object_array', $array, $class, $id, $object );
 $content = \apply_filters( 'activitypub_the_content', $content, $post );
-$actor = \apply_filters( 'activitypub_actor_data', $actor, $user_id );
+$types   = \apply_filters( 'activitypub_actor_types', $types );
 ```
 
 ## Version Numbers

.agents/skills/integrations/SKILL.md

@@ -14,14 +14,32 @@ All integrations live in the `integration/` directory.
 
 **File naming:** `class-{plugin-name}.php` (following PHP conventions in AGENTS.md)
 
-### Available Integrations
-- BuddyPress
-- bbPress
-- WooCommerce
-- Jetpack
-- The Events Calendar
-- WP User Avatars
-- And 13+ more
+**Namespace:** `Activitypub\Integration`
+
+### How Integrations Load
+Integrations are wired up in `integration/load.php` inside `plugin_init()`. Each one is guarded by a detection check and then calls its class's static `init()`:
+
+```php
+// integration/load.php
+if ( \defined( 'JETPACK__VERSION' ) ) {
+    Jetpack::init();
+}
+```
+
+### Existing Integrations
+The real integrations shipped today (see `integration/`):
+
+`akismet`, `buddypress`, `classic-editor`, `enable-mastodon-apps`, `jetpack`,
+`litespeed-cache`, `multisite-language-switcher`, `nodeinfo`, `opengraph`,
+`podlove-podcast-publisher`, `seriously-simple-podcasting`, `surge`, `webfinger`,
+`wp-rest-cache`, `wpml`, `yoast-seo`.
+
+A few examples:
+- **Akismet** — runs inbound comments/interactions through Akismet spam checks.
+- **OpenGraph** — adds `fediverse:creator` and related metadata via the OpenGraph plugin.
+- **Enable Mastodon Apps** — lets Mastodon client apps talk to the site.
+- **Caches (LiteSpeed Cache, Surge, WP REST Cache)** — keep ActivityPub responses cacheable/uncached correctly.
+- **Multilingual (WPML, Multisite Language Switcher)** — language-aware actor and content handling.
 
 For complete directory structure and naming conventions, see `docs/php-class-structure.md`.
 
@@ -34,58 +52,80 @@ For complete directory structure and naming conventions, see `docs/php-class-str
 namespace Activitypub\Integration;
 
 class Plugin_Name {
+    /**
+     * Initialize the class, registering WordPress hooks.
+     */
     public static function init() {
-        \add_filter( 'activitypub_transformer', array( self::class, 'custom_transformer' ), 10, 2 );
-        \add_filter( 'activitypub_post_types', array( self::class, 'add_post_types' ) );
+        // Enable federation for the plugin's post type.
+        \add_post_type_support( 'plugin_post_type', 'activitypub' );
+
+        // Provide a custom transformer if the default Post transformer is not enough.
+        \add_filter( 'activitypub_transformer', array( self::class, 'transformer' ), 10, 3 );
     }
 
-    public static function custom_transformer( $transformer, $object ) {
-        // Return custom transformer if needed.
+    /**
+     * Return a custom transformer for the plugin's objects.
+     *
+     * @param mixed  $transformer  The transformer to use. Default null.
+     * @param mixed  $data         The object to transform.
+     * @param string $object_class The class of the object to transform.
+     * @return mixed
+     */
+    public static function transformer( $transformer, $data, $object_class ) {
+        if ( 'WP_Post' === $object_class && 'plugin_post_type' === $data->post_type ) {
+            require_once __DIR__ . '/class-custom-transformer.php';
+            return new Custom_Transformer( $data );
+        }
         return $transformer;
     }
+}
+```
 
-    public static function add_post_types( $post_types ) {
-        // Add plugin's post types.
-        $post_types[] = 'plugin_post_type';
-        return $post_types;
-    }
+Then register it in `integration/load.php`:
+
+```php
+if ( \defined( 'PLUGIN_VERSION' ) ) {
+    Plugin_Name::init();
 }
 ```
 
 ## Integration Patterns
 
-### Adding Post Type Support
+### Enabling Federation for a Post Type
+
+Post-type support drives which content federates. Use `add_post_type_support()` — there is no `activitypub_post_types` filter:
 
 ```php
-public static function add_post_types( $post_types ) {
-    $post_types[] = 'event';
-    $post_types[] = 'product';
-    return $post_types;
-}
+\add_post_type_support( 'event', 'activitypub' );
+\add_post_type_support( 'product', 'activitypub' );
 ```
 
+The enabled post types are stored in the `activitypub_support_post_types` option (read with `\get_option( 'activitypub_support_post_types', array( 'post' ) )`).
+
 ### Custom Transformers
 
+The `activitypub_transformer` filter takes **three** arguments — `( $transformer, $data, $object_class )` — and is registered with priority `10, 3`:
+
 ```php
-public static function transformer( $transformer, $object ) {
-    if ( 'custom_type' === get_post_type( $object ) ) {
-        require_once __DIR__ . '/transformer/class-custom.php';
-        return new Transformer\Custom( $object );
+\add_filter( 'activitypub_transformer', function ( $transformer, $data, $object_class ) {
+    if ( 'WP_Post' === $object_class && 'event' === $data->post_type ) {
+        return new Event_Transformer( $data );
     }
     return $transformer;
-}
+}, 10, 3 );
 ```
 
-### Modifying Activities
+### Modifying the Activity Object
+
+To tweak the final ActivityStreams array, hook `activitypub_activity_object_array` — `( $array, $class, $id, $object )`:
 
 ```php
-\add_filter( 'activitypub_activity_object', function( $object, $post ) {
-    if ( 'product' === get_post_type( $post ) ) {
-        $object['type']  = 'Product';
-        $object['price'] = get_post_meta( $post->ID, 'price', true );
+\add_filter( 'activitypub_activity_object_array', function ( $array, $class, $id, $object ) {
+    if ( isset( $array['type'] ) && 'Note' === $array['type'] ) {
+        // Adjust the outgoing object array here.
     }
-    return $object;
-}, 10, 2 );
+    return $array;
+}, 10, 4 );
 ```
 
 ## Testing Integrations
@@ -94,7 +134,7 @@ public static function transformer( $transformer, $object ) {
 
 ```php
 // Check if integration is active.
-if ( class_exists( '\Activitypub\Integration\Plugin_Name' ) ) {
+if ( \class_exists( '\Activitypub\Integration\Plugin_Name' ) ) {
     // Integration loaded.
 }
 ```
@@ -104,23 +144,23 @@ if ( class_exists( '\Activitypub\Integration\Plugin_Name' ) ) {
 1. Install target plugin
 2. Activate ActivityPub
 3. Check for conflicts
-4. Verify custom post types work
+4. Verify custom post types federate
 5. Test federation of plugin content
 
 ## Common Integration Issues
 
 ### Plugin Detection
 ```php
-// Multiple detection methods.
-if ( defined( 'PLUGIN_VERSION' ) ) { }
-if ( function_exists( 'plugin_function' ) ) { }
-if ( class_exists( 'Plugin_Class' ) ) { }
+// Multiple detection methods (match how integration/load.php guards each one).
+if ( \defined( 'PLUGIN_VERSION' ) ) { }
+if ( \function_exists( 'plugin_function' ) ) { }
+if ( \class_exists( 'Plugin_Class' ) ) { }
 ```
 
 ### Hook Priority
 ```php
 // Use appropriate priority.
-add_filter( 'hook', 'callback', 20 ); // After plugin's filter.
+\add_filter( 'hook', 'callback', 20 ); // After plugin's filter.
 ```
 
 ### Namespace Conflicts
@@ -129,27 +169,10 @@ add_filter( 'hook', 'callback', 20 ); // After plugin's filter.
 $object = new \Plugin\Namespace\Class();
 ```
 
-## Existing Integrations
-
-### BuddyPress
-- Adds BuddyPress activity support
-- Custom member transformers
-- Group activity federation
-
-### WooCommerce
-- Product post type support
-- Order activity notifications
-- Customer review federation
-
-### bbPress
-- Forum topic federation
-- Reply activities
-- User forum profiles
-
 ## Best Practices
 
-1. **Always check if plugin is active** before adding hooks
-2. **Use late priority** for filters to override plugin defaults
-3. **Test with multiple plugin versions**
-4. **Document compatibility requirements**
-5. **Handle plugin deactivation gracefully**
+1. **Always guard the integration** with a detection check in `integration/load.php` before calling `init()`.
+2. **Use late priority** for filters when you need to override another plugin's defaults.
+3. **Test with multiple plugin versions.**
+4. **Document compatibility requirements.**
+5. **Handle plugin deactivation gracefully.**

.agents/skills/pr/SKILL.md

@@ -86,7 +86,7 @@ git push --force-with-lease
 
 ## Special Cases
 
-**Hotfixes:** Branch `fix/critical-issue`, minimal changes, add "Hotfix" label, request expedited review.
+**Hotfixes:** Branch `fix/critical-issue`, minimal changes, add a `[Pri] High` (or `[Pri] BLOCKER`) label, request expedited review.
 
 **Experimental:** Use `try/` prefix, mark as draft, get early feedback, convert to proper branch type once confirmed.
 
@@ -98,12 +98,12 @@ git push --force-with-lease
 |-------|-----|
 | `Bug` | Bug fixes |
 | `Enhancement` | New features |
-| `Documentation` | Doc updates |
+| `Docs` | Documentation updates |
 | `Code Quality` | Refactoring, cleanup, etc. |
 | `Skip Changelog` | No changelog needed |
-| `Needs Review` | Ready for review |
-| `In Progress` | Still working |
-| `Hotfix` | Urgent fix |
+| `[Status] Needs review` | Ready for review |
+| `[Status] In Progress` | Still working |
+| `[Pri] High` / `[Pri] BLOCKER` | Urgent / expedited |
 
 ## Reference
 

.agents/skills/release/SKILL.md

@@ -15,12 +15,14 @@ npm run release              # Create major/minor release PR.
 ```
 
 ### Version File Locations
-When updating versions manually, change these files:
-- `activitypub.php` - Plugin header (`Version: X.Y.Z`).
+When updating versions manually, change these files (these are the files `bin/release.js` touches):
+- `activitypub.php` - Plugin header (`Version: X.Y.Z`) **and** the `ACTIVITYPUB_PLUGIN_VERSION` constant. Both must change.
 - `readme.txt` - WordPress.org readme (`Stable tag: X.Y.Z`).
-- `package.json` - npm version (`"version": "X.Y.Z"`).
+- `includes/class-migration.php` - Version references in the DB-migration `version_compare()` checks.
 - `CHANGELOG.md` - Changelog file (auto-updated by release script).
 
+Note: `package.json` has no `version` field and is not part of the release bump.
+
 ## Comprehensive Release Guide
 
 See [Release Process](docs/release-process.md) for complete release workflow and detailed steps.

.claude/agents/bug-bounty.md

@@ -10,26 +10,23 @@ You are a bug-fix agent for the WordPress ActivityPub plugin. Your job is to pic
 
 ## Step 1 — Find an Issue to Fix
 
-Fetch open bug issues from the repository. **Only consider issues labeled "Bug" or "[Type] Bug"** — skip everything else:
+Fetch open bug issues from the repository. **Only consider issues labeled "Bug"** — skip everything else:
 
 ```bash
 gh issue list --label "Bug" --state open --json number,title,body,labels --limit 20
-gh issue list --label "[Type] Bug" --state open --json number,title,body,labels --limit 20
 ```
 
-Merge and deduplicate the results.
-
 From the results, **skip issues that also have the "Needs triage" label** — these are unverified and waiting for manual review.
 
 Review the remaining issues and pick the one that is most straightforward to fix — look for clear reproduction steps, well-described expected behavior, and a scope that can be addressed with minimal changes.
 
-**Skip issues that already have a linked PR.** For each candidate issue, check:
+**Skip issues that already have a linked PR.** For each candidate issue, check for referencing PRs:
 
 ```bash
-gh pr list --state open --search "#<number>" --json number,title
+gh search prs --repo Automattic/wordpress-activitypub --state open "Fixes #<number> OR Closes #<number> OR #<number>"
 ```
 
-If any open PR already references the issue, move on to the next candidate.
+You can also see linked PRs directly in `gh issue view <number>` (the development/timeline section). If any open PR already references the issue, move on to the next candidate.
 
 ## Step 2 — Analyze the Chosen Issue
 

.claude/agents/patch-release.md

@@ -95,9 +95,9 @@ git log --oneline -3
 
 Follow the **release** skill's patch release process:
 
-1. Run `composer changelog:write` — use the patch version when prompted.
+1. Run `composer changelog:write -- --use-version=<patch-version> --no-interaction` to force the patch version non-interactively (it otherwise derives the version from change-file significance and may prompt).
 2. Copy new entries from `CHANGELOG.md` into the `== Changelog ==` section of `readme.txt`.
-3. Update version numbers in all version file locations (per the release skill).
+3. Update version numbers in all version file locations (per the release skill). In `activitypub.php` this means **both** the `Version:` header **and** the `ACTIVITYPUB_PLUGIN_VERSION` constant, plus `includes/class-migration.php`.
 4. Replace any `unreleased` annotations in cherry-picked files with the patch version.
 
 ## Step 6 — Review Changes

.claude/agents/support.md

@@ -90,8 +90,8 @@ curl -sI -o /dev/null -w "%{http_code}" "SITE_URL/?author=1"
 # Check with Accept header for ActivityPub
 curl -s -H "Accept: application/activity+json" "SITE_URL/?author=1" | python3 -m json.tool
 
-# Also try the REST API users endpoint
-curl -s "SITE_URL/wp-json/activitypub/1.0/actors" | python3 -m json.tool
+# Also try the REST API actor endpoint (requires a numeric ID — there is no bare /actors list route)
+curl -s -H "Accept: application/activity+json" "SITE_URL/wp-json/activitypub/1.0/actors/1" | python3 -m json.tool
 ```
 
 - Verify author pages are not blocked (some security plugins block `?author=` enumeration)