humanmade / humanmade/accelerate-ai-toolkit

Wire block-runner into the markup-emitting skills

Open
#18 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
8
Forks
0
Avg merge
5h 18m
Merged PRs (30d)
3

Description

## Problem

Skills that compose block markup still validate it by hand against the §2 tables in `design-standards.md`: the model eyeballing its own output. block-runner 0.8.0 is published and does this properly (headless Gutenberg round-trip, `validate` / `fix` / `convert`, already on the WordPress 7.1 runtime), and the integration design is fully written on `feat/block-runner-integration`, but none of it is merged or wired in. The branch is sitting as a save-point at `b3b7165`.

## Solution

Land the branch and connect the loop. Three parts:

1. **Merge the docs** (`docs/block-runner.md`, the `design-standards.md` and `brand-pack.md` edits) with one trim: the `context --rest` example promises a hosted-site REST transport that shipped block-runner does not have yet (0.8.0's `context` is WP-CLI only). Mark that section as pending upstream, or cut it until the REST collector ships.
2. **Wire the pre-flight loop into every skill that emits block markup**: validate, and on failure fix then re-validate, before any variant is shown to the user or sent to a write ability. The `skills/accelerate-test/SKILL.md` edit on the branch is the pattern; the other composing skills need the same treatment.
3. **Check the bundled skill first.** 0.8.0 ships `block-runner skill --install` with a canonical, vendor-maintained agent guide. Before merging our hand-written doc, check what it covers: no point maintaining a duplicate that drifts.

The fail-open contract in the branch doc is binding: validation is an assist, never a gate. If `npx` fails, times out, or the headless boot dies, skills fall back to today's hand-validation and say so. A usage error (exit 2) warns loudly instead, since that signals a broken invocation rather than an infra blip.

## Out of scope

- The REST collector for `context` (reading hosted sites over Application Passwords). That work lives upstream in block-runner/wesper, per DEC-001 phase P1: the toolkit fails open to `get-site-context` until it exists.
- Any brand, composition, or conversion judgment. block-runner answers "will WordPress accept this markup?" and nothing else.

## Notes

- Acceptance: a composed variant with deliberately broken markup gets caught and repaired (or withheld) before presentation, verified against a real site; with block-runner unreachable, the same skill completes on the fallback path and tells the user.
- Context: `DECISIONS.md` DEC-001 records the phased plan, `docs/block-runner.md` on the branch has the full contract.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by inspecting commit b3b7165 and comparing the bundled `block-runner skill --install` guide with `docs/block-runner.md`, `design-standards.md`, and `brand-pack.md`; remove or mark the unsupported `context --rest` example. Then review `skills/accelerate-test/SKILL.md` and the other markup-emitting skills. Done means broken markup is repaired or withheld, while an unavailable runner uses the documented fallback and reports it.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, python, wordpress
Domain
documentation, testing-qa, tooling, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.