Voyager Open Blocks

WordPress blocks, binding sources and patterns that an AI agent can use correctly. Each one has a SKILL.md that teaches one loop: read the site with Wesper, author native blocks with Block Runner, then bind them to real data.

Start an agent at skills/voyager-open-blocks. The skills follow the open Agent Skills layout (skills/<name>/SKILL.md), so any harness that reads that layout can load them.

Requires WordPress 6.9+ and PHP 8.1+. Patterns use core blocks and the active theme's presets only, so the theme decides how they look.

Install

Download voyager-open-blocks.zip from the latest release. Upload it under Plugins > Add New Plugin > Upload Plugin, or run wp plugin install voyager-open-blocks.zip --activate. The zip holds one voyager-open-blocks/ folder with the blocks already built.

With Composer, add this repository and require the package (build/ is committed, so no build step is needed):

composer config repositories.voyager-open-blocks vcs https://github.com/voyager-marketing/voyager-open-blocks
composer require voyager-marketing/voyager-open-blocks

To give a coding agent the pack's skills (the read, check, bind loop and one skill per item):

npx skills add voyager-marketing/voyager-open-blocks

Abilities

Five WordPress abilities (category voyager-open-blocks, REST at wp-abilities/v1, MCP through the WordPress MCP adapter) let an agent use the pack on a live site without writing markup: get-catalog, get-post-blocks, insert, configure and bind. insert takes copy for a pattern's named headings, paragraphs, buttons and list items. get-post-blocks reports resolution for every binding (resolved or fell_back, with a reason and a value preview), so a bound value can be proved without rendering the page; node scripts/binding-resolution-check.mjs --site <dir> (npm run check:resolution) checks it against a local site. bind accepts only args that match a listed field exactly. configure touches only blocks that save no HTML. See the entry skill.

Try it

WordPress Playground blueprints load the pack with demo content: blueprint.json for everything, or one per item in blueprints/. They install the plugin from this repository's main branch.

How it is built

• Blocks live in src/<name>/ and build with @wordpress/scripts (npm run build, which writes build/blocks-manifest.php). The plugin registers everything in that manifest. build/ is committed so a Git install works without a build step.
• Patterns start as Block Runner intent trees in patterns/intents/<name>.json, with the pattern's title, description and categories beside the tree. npm run patterns:build assembles each one into patterns/<name>.html and fails on any invalid block or dropped attribute. Do not edit the .html files by hand.
• Binding sources are in inc/site-data.php and inc/post-meta-text.php. Their editor half (field lists, live values, in-place editing of post meta) is assets/bindings-editor.js.

The two binding sources keep the names they have in the voyager-blocks plugin, so content written for either resolves on both. When voyager-blocks is active it registers them first, and this plugin stands aside. get-catalog and bind then use the owning plugin's fields, read from its voyager_binding_sources definition. node scripts/foreign-owner-check.mjs --site <dir> checks that against a local site, with tests/fixtures/foreign-site-data.php standing in for the owner.

Development

Node ^22.23.4 || ^24.22.1 || >=26.12.1 (Block Runner 1.0.0's range; .nvmrc pins 24.22.1).

npm install
npm run build              # blocks
npm run patterns:build     # intents -> patterns/*.html
npm run check              # every offline gate, below

npm run check fails unless:

1. every patterns/*.html matches its intent,
2. block-runner validate --strict passes on all pattern markup,
3. the same validator rejects tests/invalid/, so the gate is shown to bite,
4. block-runner plugin inspect recognizes the plugin as a @wordpress/scripts host. On Windows this step is skipped: Block Runner 1.0.0 compares __DIR__ . '/build' with a native path and never matches a backslash path.
5. Stable tag in readme.txt matches Version in voyager-open-blocks.php.
6. tests/fixtures/site-data-keys.json matches the hash in tests/fixtures/site-data-keys.sha256.

Local site

A throwaway WordPress on SQLite that WP-CLI, Playground and Wesper all read from the same files. It needs wp and php on PATH.

npm run playground -- setup --site ../voyager-open-blocks-site   # install WordPress + SQLite, link this checkout, seed demo pages
npm run playground -- serve --site ../voyager-open-blocks-site   # serve it with Playground at http://127.0.0.1:9400
npm run context -- --site ../voyager-open-blocks-site            # wesper collect, then check every item is listed
npm run playground -- blueprint cta-band                         # boot blueprints/cta-band.json with this checkout mounted

With the site served, npm run e2e -- --context site.context.json runs the abilities end to end over REST, the way an agent would. It creates a page, inserts the CTA band twice (as shipped, then with copy), then inserts, configures and binds an icon. It checks that bad input is refused, runs block-runner validate --strict on every markup returned and on the saved page, and checks the bound values render. It reads an application password from VOYAGER_OPEN_APP_PASSWORD (wp user application-password create admin e2e --porcelain). setup sets WP_ENVIRONMENT_TYPE to local so application passwords work over plain HTTP.

npm run context fails if Wesper's manifest is missing any block, binding source or pattern in this repo, or carries a warning that names one. Other warnings are printed. WordPress 7.1.3 itself produces three (core/navigation and core/query provide context from attributes they no longer register), with or without this plugin.

npm run check:site-data -- --site ../voyager-open-blocks-site writes the untidy options in tests/fixtures/site-data-keys.json to the site, runs values() through wp eval-file, compares all 18 voyager/site-data keys to the fixture's expected values and prints ok: 18 site-data keys match the fixture. It puts the previous option values back, pass or fail, and exits non-zero on the first mismatch. {{year}} in expected stands for the current UTC year. The voyager_site_* options are written with their sanitize filters removed, so the check pins values() and not the settings page.

Two setup details that matter: the SQLite journal mode is set to DELETE, because Playground's WebAssembly PHP cannot share WAL's index with host PHP. And the site lives outside the checkout, because the checkout is linked into it.

Releases

npm run zip writes voyager-open-blocks.zip from the files list in package.json. Pushing a v* tag runs release.yml: it builds, zips, checks the zip and attaches it to the tag's GitHub release, creating the release if it does not exist. A tag with a suffix (v0.2.0-rc.1) makes a pre-release. The tag's version, without the suffix, must match Version in voyager-open-blocks.php, and a version bump moves Stable tag in readme.txt with it.

readme.txt is the WordPress.org listing. The zip ships it, and Plugin Check (wp plugin install plugin-check --activate, then wp plugin check voyager-open-blocks) should report no errors on the plugin installed from the zip. Run against this checkout linked into a site, it also reports files the zip leaves out (.git, dotfiles, playground/).

Support

Issues are answered within two business days. Support hours are Monday to Friday, 9am to 5pm US Eastern time, outside US public holidays. Releases ship in batches every two weeks. Questions go to Discussions, bugs and feature requests to issues, and security problems to private reporting (SECURITY.md). How to contribute is in CONTRIBUTING.md.

License

GPL-2.0-or-later. "Voyager" and "Voyager Open Blocks" are Voyager Marketing’s names; the license covers the code, not the names. Icons are from Heroicons (MIT, assets/LICENSE-heroicons.txt).