Primitives reference

Primitives are the building blocks the AI composes into blueprints. Each primitive is an audited, fixed-behaviour unit. This page is the canonical reference for every primitive's shape and fields.

How primitives compose

A blueprint is a JSON object with sections — register for compile-phase primitives, trigger for the runtime trigger, condition (optional), and actions for runtime primitives. Example skeleton:

{
  "type": "feature",
  "name": "Content completeness",
  "register": [ /* compile primitives */ ],
  "trigger": { /* trigger primitive */ },
  "condition": { /* optional */ },
  "actions": [ /* action primitives */ ]
}

Compile primitives

These run when the feature activates and on every WordPress load. They register structural elements with WordPress.

post_type — register a custom post type

{
  "type": "post_type",
  "slug": "case_study",
  "label": "Case Studies",
  "singular": "Case Study",
  "supports": ["title", "editor", "thumbnail", "excerpt"],
  "public": true,
  "show_in_rest": true,
  "menu_icon": "dashicons-portfolio"
}

taxonomy — register a taxonomy

{
  "type": "taxonomy",
  "slug": "industry",
  "label": "Industries",
  "post_types": ["case_study", "post"],
  "hierarchical": true,
  "show_in_rest": true
}

metabox — add a metabox to the post editor

{
  "type": "metabox",
  "id": "seo_meta",
  "title": "SEO Settings",
  "post_types": ["post", "page"],
  "context": "side",
  "priority": "high",
  "fields": [
    { "key": "meta_title", "type": "text", "label": "Meta title", "max_length": 60 },
    { "key": "meta_desc", "type": "textarea", "label": "Meta description", "max_length": 160 },
    { "key": "robots", "type": "select", "label": "Robots", "options": ["index", "noindex"] }
  ]
}

Field types: text, textarea, number, checkbox, select, multiselect, date, color, url, email, media, post_picker, term_picker, user_picker.

admin_column — add a column to the posts list

{
  "type": "admin_column",
  "post_types": ["post"],
  "key": "completeness",
  "label": "Completeness",
  "source": { "meta": "_clautron_completeness_score" },
  "format": "percentage_bar",
  "sortable": true,
  "width": "120px"
}

Format options: text, number, percentage_bar, icon, badge, date, relative_date.

admin_filter — dropdown filter above the posts list

{
  "type": "admin_filter",
  "post_types": ["post"],
  "key": "completeness_range",
  "label": "Completeness",
  "options": [
    { "value": "high", "label": "80–100%", "query": { "meta": "_clautron_completeness_score", "compare": ">=", "value": 80 } },
    { "value": "low", "label": "0–40%", "query": { "meta": "_clautron_completeness_score", "compare": "<", "value": 40 } }
  ]
}

rest_route — register a REST endpoint

{
  "type": "rest_route",
  "method": "GET",
  "path": "/posts/completeness",
  "permission": "edit_posts",
  "actions": [ /* runtime actions to execute */ ]
}

Routes are mounted at /wp-json/clautron/v1/{path}. Permission can be a WordPress capability or public.

head_inject — inject HTML into <head>

{
  "type": "head_inject",
  "context": "single_post",
  "html": "<meta name='description' content='{{post.meta.meta_desc}}'>"
}

Context options: frontend, admin, single_post, archive, home.

Trigger primitives

save_post

{
  "trigger": "save_post",
  "post_types": ["post", "page"],
  "skip_revisions": true,
  "skip_autosave": true,
  "on_status": ["publish", "draft"]
}

schedule

{
  "trigger": "schedule",
  "schedule_type": "recurring",
  "cron_expression": "0 8 * * 1"
}

hook

{
  "trigger": "hook",
  "hook_name": "user_register",
  "priority": 10
}

rest_api

{
  "trigger": "rest_api",
  "method": "POST",
  "path": "/incoming/lead",
  "permission": "public"
}

Condition primitives

condition — guard before actions run

{
  "condition": {
    "all": [
      { "field": "post.status", "compare": "==", "value": "publish" },
      { "field": "post.meta._featured_image", "compare": "exists" }
    ]
  }
}

Compare operators: ==, !=, >, >=, <, <=, contains, matches, exists, empty, in, not_in.

Combiners: all (AND), any (OR), none (NOR). Conditions can nest.

Action primitives

set_post_meta

{
  "type": "set_post_meta",
  "post_id": "{{trigger.post_id}}",
  "key": "_clautron_completeness_score",
  "value": "{{previous.score}}"
}

update_post

{
  "type": "update_post",
  "post_id": "{{trigger.post_id}}",
  "fields": { "post_status": "draft" },
  "dry_run": false
}

delete_post

{
  "type": "delete_post",
  "post_id": "{{loop.id}}",
  "force": false,
  "dry_run": true
}

send_email

{
  "type": "send_email",
  "to": "{{site.admin_email}}",
  "subject": "Daily summary",
  "body": "{{previous.report.summary}}",
  "is_html": false
}

data_query

{
  "type": "data_query",
  "source": "posts",
  "filters": {
    "post_type": "post",
    "post_status": "publish",
    "date_after": "{{date.today|minus:30d}}"
  },
  "fields": ["ID", "post_title", "post_date", "comment_count"],
  "sort": { "field": "post_date", "direction": "desc" },
  "limit": 100,
  "store_as": "recent_posts"
}

publish_gate

{
  "type": "publish_gate",
  "block_message": "This post needs a featured image before publishing.",
  "condition": {
    "field": "post.featured_image",
    "compare": "empty"
  }
}

loop — iterate over a previous query result

{
  "type": "loop",
  "source": "{{previous.recent_posts}}",
  "as": "loop",
  "actions": [ /* run for each item, with {{loop.*}} available */ ]
}

http_request

{
  "type": "http_request",
  "method": "POST",
  "url": "https://hooks.example.com/incoming",
  "headers": { "Authorization": "Bearer {{secret.WEBHOOK_TOKEN}}" },
  "body": { "title": "{{post.title}}" },
  "store_as": "webhook_response"
}

HTTP requests respect a 10-second timeout and a 1MB response cap. Domain allowlist is configurable in Clautron → Settings.