Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ For these teams, Workflows is about approvals. The question each story answers i
**M4. A research blog replaces custom statuses and email chains.** A team whose process was Draft → Design Review → Editorial Approval → Author Sign-off → Scheduled models it one stage per step. Transitions send email or Slack messages to configured recipients, and everyone can see live status in WordPress instead of in a separate tracker.
*Always true:* notifications are sent after a move commits. A failing channel never blocks or rolls back a move. → [Notifications](#notifications)

**M5. A team sets up a workflow by describing it.** Someone connected over MCP describes their process in plain language (for example, an eight-stage approval flow), and an agent creates the sequence through the `create-sequence` ability. The sequence is active by default, or saved as a draft for review when the caller asks.
**M5. A team sets up a workflow by describing it.** Someone connected over MCP describes their process in plain language (for example, an eight-stage approval flow), and an agent creates the sequence through the `create-sequence` ability. The sequence is active by default, or saved as a draft for review when the caller asks. In the WordPress AI plugin's AI Workspace, the agent can only propose the sequence: the person sees its stages on an approval card, and approving creates it as a draft.
*Always true:* sequences created over MCP or REST go through the same validation as the sequence editor. The sequence schema is the contract. → [Sequences and stages](#sequences-and-stages), [REST and Abilities](#rest-and-abilities)

### Admins and developers
Expand Down Expand Up @@ -344,6 +344,7 @@ Audit-log rows are limited to the user's own actions unless their role is in `au
| Ability id | Does | Permission callback |
| --- | --- | --- |
| `vip-workflows/create-sequence`, `import-sequence`, `update-sequence`, `activate-sequence`, `validate-sequence` | Author and activate sequences (import creates a draft; update is a full replace) | `manage_options`; MCP public |
| `vip-workflows/propose-sequence` | Store a proposed sequence on an AI Workspace approval card; approval creates it as a draft. Registered only while the WordPress AI plugin's `Proposal_Kind` interface exists, and refused outside an AI Workspace turn | `manage_options`, re-checked at approval; not in REST or MCP |
| `vip-workflows/transition-post` | Move a post along its sequence, through the same gate as REST | `edit_posts`, then `edit_post` in execute; MCP public |
| `vip-workflows/remove-from-workflow` | Clear a post's sequence (audited), leaving its status | `edit_posts`, then `edit_post`; MCP public |
| `vip-workflows/update-post-fields` | Change title, excerpt, date or author (an author change needs `edit_others_posts`) | `edit_posts`, then `edit_post`; MCP public |
Expand Down Expand Up @@ -714,6 +715,8 @@ flowchart LR
- **Required metadata doesn't hold back a status change from outside the workflow.** A scheduled post going live, or a Quick Edit to Published, reseats the post with required fields still empty.
- **Only the editor makes new posts join a workflow.** Posts created over REST, WP-CLI or Quick Draft have no workflow until someone assigns one.
- **Phase transitions follow different rules from workflow transitions.** They don't consult the bypass list or the tool-check bypass list, and unacknowledged soft warnings return a 422 `tool_check_warnings` error instead of the 200 `warnings_pending` response workflow transitions use.
- **A sequence created as a draft is active for a moment.** `create_item()` inserts the row as `active` and then sets `draft` in a second write, so a failure between the two leaves an active sequence. This covers `create-sequence` with `status: draft` and AI Workspace approvals.
- **The AI Workspace proposal kind follows an internal interface.** The WordPress AI plugin marks `Proposal_Kind` internal, so a change there can break `SequenceProposal` without notice. The module checks the interface exists, not its shape.
- **A Story's status changes only twice.** It is set on create (`ideation` or `editorial`) and on Create Draft (`ideation` → `editorial`). Nothing moves a Story to `published`, `monitoring` or `refresh`.

**Code**
Expand All @@ -728,6 +731,7 @@ flowchart LR
- `vip-workflows/includes/class-plugin.php`: `Plugin::register_metadata_fields()` registers `config.metadata_fields` (types `text`, `textarea`, `select`, `date`, `user`) as `wf_meta_{sequence_id}_{key}`, `show_in_rest`, `auth_callback` = `edit_post`; `required` fields.
- `vip-workflows/includes/api/class-sequences-controller.php`: `SequencesController::create_item()` and `update_item()`, which run `validate_metadata_fields()`, `validate_status_agents()`, `validate_assignment_keys()` and `build_config()`. Routes `GET /sequences/{id}/export` (returns `name`, `type`, `description`, `config`) and `POST /sequences/import`.
- `vip-workflows/includes/abilities/tools/`: abilities `create-sequence`, `update-sequence`, `import-sequence` (build a `WP_REST_Request`), `activate-sequence`, `validate-sequence`.
- `vip-workflows/includes/ai-workspace/`: the AI Workspace integration. `AIWorkspace` adds the `workflow` kind on the AI plugin's `wpai_workspace_proposal_kinds` filter. `SequenceProposal` validates through `validate-sequence` and creates through `create-sequence`. `ProposeSequence` registers `vip-workflows/propose-sequence`.
- Phase sequence (`type: 'phase'`): transition fields `label`, `required_tools`, `allowed_roles`, `notifications`; seeded as `content-lifecycle` by `IdeationExperiment::activate()` (`vip-workflows/includes/experiments/class-ideation-experiment.php`) → `Seeder::seed_phase_sequence()` (`vip-workflows/includes/database/class-seeder.php`); checked in `IdeationController::create_draft()` and `check_phase_transition()` (`vip-workflows/includes/api/class-ideation-controller.php`).
- Settings not consulted by phase transitions: `bypass_workflow_roles`, `bypass_tool_check_roles`. Phase error `tool_check_warnings`.
- Sequence statuses mentioned: `draft`, `archived`. Story statuses: `ideation`, `editorial`, `published`, `monitoring`, `refresh`.
Expand Down
81 changes: 81 additions & 0 deletions vip-workflows/includes/ai-workspace/class-ai-workspace.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
<?php
/**
* WordPress AI Workspace integration.
*
* @package VIPWorkflows
*/

declare( strict_types=1 );

namespace VIPWorkflows\AiWorkspace;

use VIPWorkflows\ModuleInterface;

/**
* Lets the WordPress AI plugin's AI Workspace propose a workflow sequence for a person to approve.
*
* It adds the `workflow` proposal kind and its propose ability, and does
* nothing unless the AI plugin's proposal interface exists. That interface is
* internal to the AI plugin, so this integration is experimental.
*/
final class AIWorkspace implements ModuleInterface {

/**
* The AI plugin interface a proposal kind implements.
*/
private const PROPOSAL_KIND_INTERFACE = '\WordPress\AI\Experiments\AI_Workspace\Proposal_Kind';

/**
* {@inheritDoc}
*/
public function get_id(): string {
return 'ai-workspace';
}

/**
* {@inheritDoc}
*/
public function init(): void {
add_filter( 'wpai_workspace_proposal_kinds', array( $this, 'add_proposal_kind' ) );
// After core's own abilities (priority 10), whose create-sequence schema the propose ability reuses.
add_action( 'wp_abilities_api_init', array( $this, 'register_ability' ), 11 );
}

/**
* Whether the AI plugin's proposal interface is loaded.
*
* @return bool
*/
public static function is_available(): bool {
return interface_exists( self::PROPOSAL_KIND_INTERFACE );
}

/**
* Adds the `workflow` kind to the AI Workspace's proposal kinds.
*
* @param mixed $kinds The kinds.
* @return mixed The kinds, with this one added.
*/
public function add_proposal_kind( $kinds ) {
if ( ! is_array( $kinds ) || ! self::is_available() ) {
return $kinds;
}

$kinds[] = new SequenceProposal();

return $kinds;
}

/**
* Registers the propose ability while the AI Workspace can store proposals.
*
* @return void
*/
public function register_ability(): void {
if ( ! self::is_available() ) {
return;
}

ProposeSequence::register();
}
}
183 changes: 183 additions & 0 deletions vip-workflows/includes/ai-workspace/class-propose-sequence.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
<?php
/**
* The `vip-workflows/propose-sequence` ability.
*
* @package VIPWorkflows
*/

declare( strict_types=1 );

namespace VIPWorkflows\AiWorkspace;

use WordPress\AI\Experiments\AI_Workspace\Proposal_Store;
use WordPress\AI\Experiments\AI_Workspace\Turn_Context;
use WP_Error;

/**
* Registers the ability the AI Workspace model calls to propose a workflow sequence.
*
* It writes nothing. It stores the proposed sequence with the AI plugin's
* proposal store, which shows it to the person on an approval card, and
* {@see SequenceProposal::write()} creates it once they approve. It is hidden
* from REST and MCP, and refuses outside an AI Workspace turn, because a
* proposal only means something where the person who approves it is.
* `create-sequence` stays the MCP path for creating a sequence directly.
*/
final class ProposeSequence {

/**
* The ability name.
*/
public const ABILITY = 'vip-workflows/propose-sequence';

/**
* Registers the ability. Runs on `wp_abilities_api_init`.
*
* @return void
*/
public static function register(): void {
wp_register_ability(
self::ABILITY,
array(
'label' => __( 'Propose workflow', 'vip-workflows' ),
'description' => __( 'Records one proposed editorial workflow (a VIP Workflows sequence) for the person to review. This writes nothing: it stores the exact name, description, stages and post types you propose and returns a proposal identifier, and the person must approve them before the sequence is created, as a draft. Give every stage a key, a label and a status region (draft, pending, private or publish), and the transitions out of it; the stages are checked with the same rules as the sequence editor.', 'vip-workflows' ),
'category' => 'vip-workflows',
'input_schema' => self::input_schema(),
'output_schema' => self::output_schema(),
'execute_callback' => array( self::class, 'execute' ),
'permission_callback' => array( self::class, 'check_permission' ),
'meta' => array(
'show_in_commands' => false,
'transition_eligible' => false,
'annotations' => array(
'readonly' => false,
'destructive' => false,
'idempotent' => false,
'open_world' => false,
),
// MCP exposure reads `mcp.public`, not `show_in_rest`; both are off.
'show_in_rest' => false,
'mcp' => array( 'public' => false ),
),
)
);
}

/**
* Permission callback.
*
* @return bool Whether the current user may propose a sequence.
*/
public static function check_permission(): bool {
return current_user_can( SequenceProposal::CAPABILITY );
}

/**
* Stores the proposal.
*
* @param array<string, mixed> $input The ability input, already checked against the input schema.
* @return array<string, mixed>|\WP_Error The stored proposal summary, or an error.
*/
public static function execute( array $input ) {
if ( ! Turn_Context::is_active() ) {
return new WP_Error(
'vip_workflows_workspace_context_required',
__( 'Workflows can only be proposed inside an AI Workspace conversation, where a person can approve them.', 'vip-workflows' ),
array( 'status' => 403 )
);
}

$proposal = ( new Proposal_Store() )->create(
get_current_user_id(),
Turn_Context::get_conversation_id(),
array( $input ),
SequenceProposal::KIND
);

if ( is_wp_error( $proposal ) ) {
return $proposal;
}

$item = $proposal['items'][0];

return array(
'proposal_id' => $proposal['id'],
'item_count' => 1,
'expires' => $proposal['expires'],
'confirmation_required' => true,
'items' => array(
array(
'key' => $item['key'],
'name' => $item['name'],
),
),
'note' => __( 'Nothing has been created. The person now sees the stored workflow and chooses whether to create it as a draft sequence. Do not claim the workflow exists, and do not propose it again unless they ask.', 'vip-workflows' ),
);
}

/**
* The input schema: the fields of `create-sequence` a proposal carries.
*
* The stage schema is `create-sequence`'s own, so the two never drift.
*
* @return array<string, mixed> The schema.
* @throws \LogicException When create-sequence is not registered, which is a load-order bug.
*/
private static function input_schema(): array {
include_once dirname( __DIR__ ) . '/abilities/tools/create-sequence.php';

$create = wp_get_ability( 'vip-workflows/create-sequence' );

if ( null === $create ) {
throw new \LogicException( 'vip-workflows/create-sequence must be registered before vip-workflows/propose-sequence.' );
}

$properties = $create->get_input_schema()['properties'];

return array(
'type' => 'object',
'additionalProperties' => false,
'required' => array( 'name', 'statuses', 'post_types' ),
'properties' => array(
'name' => $properties['name'],
'description' => $properties['description'],
'statuses' => $properties['statuses'],
'post_types' => array(
'type' => 'array',
'description' => __( 'Post types the workflow applies to, such as "post". At least one.', 'vip-workflows' ),
'items' => array( 'type' => 'string' ),
'minItems' => 1,
),
),
);
}

/**
* The output schema.
*
* @return array<string, mixed> The schema.
*/
private static function output_schema(): array {
return array(
'type' => 'object',
'additionalProperties' => false,
'properties' => array(
'proposal_id' => array( 'type' => 'string' ),
'item_count' => array( 'type' => 'integer' ),
'expires' => array( 'type' => 'integer' ),
'confirmation_required' => array( 'type' => 'boolean' ),
'items' => array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'key' => array( 'type' => 'string' ),
'name' => array( 'type' => 'string' ),
),
),
),
'note' => array( 'type' => 'string' ),
),
);
}
}
Loading
Loading