Summary

Add a required category system to the WordPress Abilities API to enable organizing, filtering, and discovering abilities by functional domain. Every ability must be assigned to a category.

---

Problem

The Abilities API currently lacks a native way to:

• Organize abilities by functional area (content, users, e-commerce, etc.)
• Filter abilities in REST API queries
• Group related abilities for UI rendering and documentation
• Enable taxonomy-style organization

---

Proposed Solution

Implement a category system with these characteristics:

• Required property - Every ability must have a category assigned
• Required registration - Categories must be registered before they can be assigned to abilities
• First-class property - Category stored as ability property, not in metadata
• Registry pattern - Category registry manages all available categories with labels and descriptions
• REST API integration - Native filtering via query parameters
• WordPress patterns - Follows post types/taxonomies conventions

---

Core Components

1. Category Class

New: WP_Ability_Category

Properties:

• slug - Unique identifier (pattern: ^[a-z0-9-]+$)
• label - Human-readable name
• description - Detailed description

2. Category Registry

New: WP_Abilities_Category_Registry

Pattern: Singleton registry (required for all categories)

Functionality:

• Register/unregister categories
• Retrieve categories by slug
• List all registered categories
• Check if category is registered (used during ability registration)
• Validate category before ability assignment

Hook: abilities_api_category_registry_init

3. Ability Integration

Enhancement: WP_Ability class

New Property: category (string, required)

Validation:

• Must be a non-empty string
• Enforce slug pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Lowercase alphanumeric characters and dashes only

4. Helper Functions

New functions in abilities-api.php:

Registration:

• wp_register_ability_category()
• wp_unregister_ability_category()

Retrieval:

• wp_get_ability_category()
• wp_get_ability_categories()

Filtering:

• wp_get_abilities_by_category()

5. REST API

Schema Enhancement:

• Add category field to ability response
• Type: string with pattern validation
• Context: view, edit, embed
• Readonly: true
• Required: true

Query Parameter:

• GET /wp/v2/abilities?category=content
• Filter abilities before pagination
• Return standard paginated response

6. Registry Enhancement

New method in WP_Abilities_Registry:

• get_abilities_by_category() - Filter abilities by category slug

---

Proposed Design Approach

1. Required Category Property with Required Registration

Proposal: Every ability must have a category, and categories must be formally registered before they can be assigned to abilities.

Benefits:

• Ensures consistent organization across all abilities
• Prevents typos and inconsistent category names
• Provides centralized category management with labels and descriptions
• Enables better documentation and discovery of available categories
• Validates category slugs at registration time

2. Simple Category Structure

Proposal: Keep categories simple with only slug, label, and description.

Benefits:

• YAGNI principle (keep it simple)
• Clearer purpose (organization and labeling)
• Easier to understand and maintain
• Can be extended later if needed

3. First-Class Required Property

Proposal: Store category as a required direct WP_Ability property.

Benefits:

• Easier to access via $ability->get_category()
• Enforces validation rules at the class level
• Automatically included in REST API responses
• Guarantees every ability is categorized

4. Slug Pattern Enforcement

Proposal: Enforce ^[a-z0-9]+(-[a-z0-9]+)*$ pattern for category slugs.

Benefits:

• Prevents special characters, spaces, uppercase
• Ensures proper dash usage (no leading, trailing, or consecutive dashes)
• URL-safe for REST API
• Consistent with WordPress conventions
• Prevents data integrity issues

Backward Compatibility

Breaking Changes: Yes - Category is now required and must be registered

Impact:

• Categories must be registered using wp_register_ability_category() before use
• All existing abilities must be updated to include a registered category
• Ability registration without category will fail validation
• Ability registration with unregistered category will fail validation
• Existing REST API queries unaffected (category filtering is optional)
• Migration needed:
  1. Register all required categories
  2. Update all abilities to use registered categories