workflow-{name}/
  workflow-{name}.php   # Main plugin file (single file is fine for most agents)

<?php
/**
 * Plugin Name: Workflow Agent: {Display Name}
 * Description: Research agent that searches {data source} during ideation.
 * Version: 1.0.0
 * Requires Plugins: vip-workflows
 * Text Domain: workflow-agent-{name}
 *
 * @package WorkflowAgent{PascalName}
 */

declare( strict_types=1 );

namespace WorkflowAgent{PascalName};

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'wp_abilities_api_init', __NAMESPACE__ . '\register' );

function register(): void {
    if ( ! function_exists( 'vip_workflows_register_ability' ) ) {
        return;
    }

    vip_workflows_register_ability(
        'workflow-agent-{name}/{slug}',
        array(
            'label'               => __( '{Display Name}', 'workflow-agent-{name}' ),
            'description'         => __( '{One-line description of what this searches.}', 'workflow-agent-{name}' ),
            'category'            => 'research',
            'input_schema'        => array(
                'type'       => 'object',
                'properties' => array(
                    'seed'          => array( 'type' => 'string' ),
                    'seed_analysis' => array( 'type' => 'object' ),
                    'project_id'    => array( 'type' => 'integer' ),
                    'query'         => array( 'type' => 'string' ),
                    'brand_context' => array( 'type' => 'array' ),
                ),
                'required'   => array( 'seed' ),
            ),
            'output_schema'       => array(
                'type'       => 'object',
                'properties' => array(
                    'cards'   => array( 'type' => 'array' ),
                    'summary' => array( 'type' => 'string' ),
                ),
            ),
            'execute_callback'    => __NAMESPACE__ . '\execute',
            'permission_callback' => function () {
                return current_user_can( 'edit_posts' );
            },
            'meta'                => array(
                'type'             => 'research',
                'display_order'    => 50,
                'show_in_rest'     => true,
                'icon'             => 'search',
                'thinking_message' => __( 'Searching {source}...', 'workflow-agent-{name}' ),
                'success_message'  => __( '{Source} search complete.', 'workflow-agent-{name}' ),
                // Uncomment if the agent needs configuration:
                // 'settings_schema'  => array(
                //     'api_key' => array(
                //         'type'     => 'string',
                //         'label'    => 'API Key',
                //         'required' => true,
                //         'secret'   => true,
                //     ),
                //     'max_results' => array(
                //         'type'    => 'integer',
                //         'label'   => 'Max Results',
                //         'default' => 10,
                //         'minimum' => 1,
                //         'maximum' => 50,
                //     ),
                // ),
                // See the Availability section below for the callback body.
                // 'availability_callback' => __NAMESPACE__ . '\check_availability',
            ),
        )
    );
}

/**
 * Execute the research search.
 *
 * When `query` is present (manual follow-up), search that term directly.
 * Otherwise use targeted search_queries from seed analysis, falling back
 * to the raw seed only if analysis produced nothing.
 *
 * @param array $input { seed: string, seed_analysis: array, query?: string, brand_context?: array }
 * @return array { cards: array, summary: string }
 */
function execute( array $input ): array {
    $seed_analysis = $input['seed_analysis'] ?? array();

    if ( ! empty( $input['query'] ) ) {
        $queries = array( $input['query'] );
    } else {
        $queries = $seed_analysis['search_queries'] ?? array();
        if ( empty( $queries ) ) {
            $queries = array( $input['seed'] ?? '' );
        }
    }

    $queries = array_filter( $queries );
    if ( empty( $queries ) ) {
        return array( 'cards' => array(), 'summary' => 'No search query provided.' );
    }

    $all_cards = array();
    foreach ( array_slice( $queries, 0, 3 ) as $query ) {
        $all_cards = array_merge( $all_cards, search_source( $query ) );
    }

    return array(
        'cards'   => $all_cards,
        'summary' => sprintf( 'Found %d results.', count( $all_cards ) ),
    );
}

function search_source( string $query ): array {
    $url      = add_query_arg( array( 'q' => $query ), 'https://api.example.com/search' );
    $response = wp_remote_get( $url, array( 'timeout' => 10 ) );

    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return array();
    }

    $body    = json_decode( wp_remote_retrieve_body( $response ), true );
    $results = $body['results'] ?? array();
    $cards   = array();

    foreach ( array_slice( $results, 0, 10 ) as $item ) {
        $cards[] = array(
            'type'        => 'article',
            'source_type' => 'article',
            'origin'      => '{name}',
            'title'       => $item['title'] ?? '',
            'url'         => $item['url'] ?? '',
            'excerpt'     => $item['description'] ?? '',
            'content'     => $item['body'] ?? '',
            'domain'      => '{domain.com}',
            'author'      => $item['author'] ?? null,
            'date'        => $item['date'] ?? null,
            'image'       => $item['image'] ?? null,
            'source'      => '{name}',
        );
    }

    return $cards;
}

<?php
/**
 * Plugin Name: Workflow Agent: {Display Name}
 * Description: Stage-capable agent that {describes what it checks or rewrites}.
 * Version: 1.0.0
 * Requires Plugins: vip-workflows
 * Text Domain: workflow-agent-{name}
 *
 * @package WorkflowAgent{PascalName}
 */

declare( strict_types=1 );

namespace WorkflowAgent{PascalName};

use VIPWorkflows\Abilities\Agents\StageAgent;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'vip_workflows_register_abilities', __NAMESPACE__ . '\register' );
add_action( 'vip_workflows_register_assistant_meta', __NAMESPACE__ . '\register_agent_meta' );

function register(): void {
    if ( ! function_exists( 'vip_workflows_register_ability' ) || ! class_exists( StageAgent::class ) ) {
        return;
    }

    vip_workflows_register_ability(
        'workflow-agent-{name}/{slug}',
        array(
            'label'               => __( '{Display Name}', 'workflow-agent-{name}' ),
            'description'         => __( '{One-line description.}', 'workflow-agent-{name}' ),
            'category'            => 'vip-workflows',
            'input_schema'        => array(
                'type'                 => 'object',
                'additionalProperties' => false,
                'properties'           => array(
                    'post_id' => array(
                        'type'        => 'integer',
                        'description' => __( 'The post ID for this agent.', 'workflow-agent-{name}' ),
                    ),
                ),
                'required'             => array( 'post_id' ),
            ),
            'output_schema'       => array(
                'type'                 => 'object',
                'additionalProperties' => false,
                'required'             => array( 'status', 'summary' ),
                'properties'           => array(
                    'status'  => array(
                        'type' => 'string',
                        'enum' => array( 'pass', 'fail' ),
                    ),
                    'summary' => array( 'type' => 'string' ),
                    'issues'  => array( 'type' => 'array' ),
                ),
            ),
            'execute_callback'    => __NAMESPACE__ . '\execute',
            'permission_callback' => function () {
                return current_user_can( 'edit_posts' );
            },
            'meta'                => array(
                'type'                => 'agent',
                'show_in_rest'        => true,
                'show_in_commands'    => false,
                'transition_eligible' => false,
                'icon'                => 'search',
                'supports'            => array( 'workflow', 'stage' ),
                'stage_eligible'      => true,
                'annotations'         => array(
                    'readonly'    => true,
                    'destructive' => false,
                    'idempotent'  => true,
                ),
            ),
        )
    );
}

function register_agent_meta( $registry ): void {
    $registry->register(
        'workflow-agent-{name}',
        array(
            'label'        => __( '{Display Name}', 'workflow-agent-{name}' ),
            'description'  => __( '{One-line description.}', 'workflow-agent-{name}' ),
            'icon'         => 'search',
            'ability_ids'  => array( 'workflow-agent-{name}/{slug}' ),
            'capabilities' => array( 'stage' ),
        )
    );
}

function execute( ?array $input = null ) {
    $input   = $input ?? array();
    $post_id = (int) ( $input['post_id'] ?? 0 );

    if ( ! $post_id ) {
        return new \WP_Error( 'missing_post_id', __( 'A post_id is required.', 'workflow-agent-{name}' ) );
    }

    $post = StageAgent::read_post( $post_id );
    if ( is_wp_error( $post ) ) {
        return $post;
    }

    // Build your prompt or deterministic check from $post['title'] and $post['content'].
    // Return StageAgent::result( 'pass', '...' ) or StageAgent::result( 'fail', '...', array( 'issues' => $issues ) ).
}

<?php
/**
 * Plugin Name: Workflow Discovery: {Display Name}
 * Description: Story discovery provider that surfaces prompts from {data source}.
 * Version: 1.0.0
 * Requires Plugins: vip-workflows
 * Text Domain: workflow-discovery-{name}
 *
 * @package WorkflowDiscovery{PascalName}
 */

declare( strict_types=1 );

namespace WorkflowDiscovery{PascalName};

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'vip_workflows_register_discovery_providers', __NAMESPACE__ . '\register' );

function register( $registry ): void {
    $registry->register( '{provider-slug}', array(
        'label'       => __( '{Display Name}', 'workflow-discovery-{name}' ),
        'description' => __( '{One-line description of what this provider surfaces.}', 'workflow-discovery-{name}' ),
        'icon'        => 'search',
        'features'    => array( 'recommend', 'search' ), // keep only what you implement
        'callbacks'   => array(
            'recommend' => __NAMESPACE__ . '\get_recommendations', // required if 'recommend' in features
            'search'    => __NAMESPACE__ . '\search',              // required if 'search' in features
            'filters'   => __NAMESPACE__ . '\get_filters',         // required if 'search' in features
            'seed'      => __NAMESPACE__ . '\generate_seed',       // always required
        ),
        // Uncomment if credentials are needed. See the Availability section below
        // for the callback body.
        // 'availability_callback' => __NAMESPACE__ . '\check_availability',
    ) );
}

/**
 * Return curated prompts for the landing page.
 *
 * Called on page load with the provider's saved settings.
 * Return up to 6 prompts. Cache aggressively (see Caching section).
 *
 * @param array $config Provider settings (categories, regions, etc.).
 * @return array Array of story prompt arrays.
 */
function get_recommendations( array $config ): array {
    $response = wp_remote_get( 'https://api.example.com/upcoming', array( 'timeout' => 10 ) );

    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return array();
    }

    $body    = json_decode( wp_remote_retrieve_body( $response ), true );
    $results = $body['items'] ?? array();

    return array_map( __NAMESPACE__ . '\normalize_prompt', array_slice( $results, 0, 6 ) );
}

/**
 * Search for prompts matching user criteria.
 *
 * @param array $params { text: string, filters: array<string, mixed> }
 * @return array Array of story prompt arrays.
 */
function search( array $params ): array {
    $text    = $params['text'] ?? '';
    $filters = $params['filters'] ?? array();

    $url      = add_query_arg( array( 'q' => $text ), 'https://api.example.com/search' );
    $response = wp_remote_get( $url, array( 'timeout' => 10 ) );

    if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
        return array();
    }

    $body    = json_decode( wp_remote_retrieve_body( $response ), true );
    $results = $body['items'] ?? array();

    return array_map( __NAMESPACE__ . '\normalize_prompt', $results );
}

/**
 * Return search filter definitions for the modal UI.
 *
 * Supported types: 'select', 'multi_select', 'date_range'.
 * Return an empty array if the provider has no filters but supports search.
 */
function get_filters(): array {
    return array(
        array(
            'key'     => 'category',
            'label'   => __( 'Category', 'workflow-discovery-{name}' ),
            'type'    => 'select',
            'options' => array(
                array( 'value' => 'all', 'label' => 'All categories' ),
            ),
        ),
        // array(
        //     'key'     => 'date_range',
        //     'label'   => __( 'Date range', 'workflow-discovery-{name}' ),
        //     'type'    => 'date_range',
        //     'default' => array( 'from' => 'today', 'to' => '+90 days' ),
        // ),
    );
}

/**
 * Compose a seed string from a selected prompt.
 *
 * Called when an editor clicks a prompt card. The returned string becomes
 * the seed for a new ideation project. Include the most relevant context
 * your data source provides.
 */
function generate_seed( array $prompt ): string {
    $parts = array( $prompt['title'] );

    if ( ! empty( $prompt['description'] ) ) {
        $parts[] = $prompt['description'];
    }
    if ( ! empty( $prompt['date'] ) ) {
        $parts[] = sprintf( 'Scheduled for %s.', date( 'F j, Y', strtotime( $prompt['date'] ) ) );
    }
    if ( ! empty( $prompt['tags'] ) ) {
        $parts[] = sprintf( 'Topics: %s.', implode( ', ', $prompt['tags'] ) );
    }

    return implode( ' ', $parts );
}

function normalize_prompt( array $item ): array {
    return array(
        'id'          => '{provider-slug}-' . ( $item['id'] ?? '' ),
        'provider'    => '{provider-slug}',
        'title'       => $item['title'] ?? '',
        'description' => $item['description'] ?? '',
        'url'         => $item['url'] ?? '',
        'date'        => $item['date'] ?? null,
        'date_end'    => $item['date_end'] ?? null,
        'tags'        => $item['tags'] ?? array(),
        'importance'  => $item['importance'] ?? 'normal',
        'meta'        => $item['meta'] ?? array(),
    );
}

<?php
/**
 * Plugin Name: Workflow {Display Name}
 * Description: {Short description combining both capabilities.}
 * Version: 1.0.0
 * Requires Plugins: vip-workflows
 * Text Domain: workflow-{name}
 *
 * @package Workflow{PascalName}
 */

declare( strict_types=1 );

namespace Workflow{PascalName};

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// Register the research ability.
add_action( 'wp_abilities_api_init', __NAMESPACE__ . '\register_ability' );

function register_ability(): void {
    if ( ! function_exists( 'vip_workflows_register_ability' ) ) {
        return;
    }

    vip_workflows_register_ability(
        'workflow-{name}/{ability-slug}',
        array(
            'label'               => __( '{Display Name}', 'workflow-{name}' ),
            'description'         => __( '{Research description.}', 'workflow-{name}' ),
            'category'            => 'research',
            // ... input_schema, output_schema, execute_callback, permission_callback
            'meta'                => array(
                'type'         => 'research',
                'show_in_rest' => true,
                'icon'         => 'search',
            ),
        )
    );
}

// Register the discovery provider.
add_action( 'vip_workflows_register_discovery_providers', __NAMESPACE__ . '\register_provider' );

function register_provider( $registry ): void {
    $registry->register( '{provider-slug}', array(
        'label'     => __( '{Display Name}', 'workflow-{name}' ),
        'icon'      => 'search',
        'features'  => array( 'recommend', 'search' ),
        'callbacks' => array(
            'recommend' => __NAMESPACE__ . '\get_recommendations',
            'search'    => __NAMESPACE__ . '\search_prompts',
            'filters'   => __NAMESPACE__ . '\get_filters',
            'seed'      => __NAMESPACE__ . '\generate_seed',
        ),
    ) );
}

// Declare the unified manifest so both appear as a single card.
add_action( 'vip_workflows_register_assistant_meta', __NAMESPACE__ . '\register_assistant_meta' );

function register_assistant_meta( $registry ): void {
    $registry->register( 'workflow-{name}', array(
        'label'           => __( '{Display Name}', 'workflow-{name}' ),
        'description'     => __( 'Expert sources and story prompts from {source}.', 'workflow-{name}' ),
        'icon'            => 'search',
        'ability_ids'     => array( 'workflow-{name}/{ability-slug}' ),
        'provider_slugs'  => array( '{provider-slug}' ),
        'settings_schema' => array(
            'api_key' => array(
                'type'     => 'string',
                'label'    => 'API Key',
                'required' => true,
                'secret'   => true,
            ),
        ),
    ) );
}

use VIPWorkflows\Abilities\Availability;
use VIPWorkflows\Abilities\RequirementFactory;
use VIPWorkflows\Abilities\RequirementGroup;

/**
 * Whether this agent's dependencies are met, and what is missing if not.
 *
 * Registered as the `availability_callback` for both the ability and the
 * discovery provider. Sharing one callback means both contribute the same
 * requirement id, so the card renders one row listing both capabilities.
 */
function check_availability(): bool|Availability {
    if ( is_configured() ) {
        return true;
    }

    return Availability::unmet(
        RequirementGroup::all(
            RequirementFactory::in_card(
                'settings:workflow-{name}',
                __( '{Display Name} sign-in details are missing. Add the API key below.', 'workflow-{name}' ),
                __( '{Display Name} is not connected. Ask an administrator to connect it.', 'workflow-{name}' ),
                __( 'Complete the API key field below.', 'workflow-{name}' ),
                array( __( '{Display Name}', 'workflow-{name}' ) )
            )
        )
    );
}

function is_configured(): bool {
    $settings = \VIPWorkflows\Abilities\AbilitySettings::get_instance();
    $options  = $settings->get_options( 'workflow-agent-{name}/{slug}' );

    return ! empty( $options['api_key'] );
}

import { addFilter } from '@wordpress/hooks';

addFilter(
    'vipWorkflows.assistantSettings',
    'workflow-{name}',
    ( component, assistant, { disabled, onHasChangesChange, onSaveRef } ) => {
        // Match on your ability id, not on `assistant.slug`. An entry slug is
        // derived, and only a manifest controls its own: an agent with no
        // manifest gets a slug built from its whole ability id
        // (`workflow-{name}-{slug}`), so a slug comparison silently stops
        // matching. Ability ids are yours and never change under you.
        if ( ! assistant.ability_ids?.includes( 'workflow-{name}/{slug}' ) ) {
            return component;
        }

        return (
            <SettingsForm
                assistant={ assistant }
                disabled={ disabled }
                onHasChangesChange={ onHasChangesChange }
                onSaveRef={ onSaveRef }
            />
        );
    }
);