block-runner

Files (7)

• .block-runner-install.json
• SKILL.md
• ASSEMBLE.md · references/
• AUTHORING-PLAN.md · references/
• AUTHORING.md · references/
• CONSTRUCTION-PATTERNS.md · references/
• GUIDE.md · references/

SKILL.md (first lines)

# Block Runner

## Pick the artifact first

Choose the visible result before discovering a project. Read the named first reference, use the
condition, and stop at its stated boundary. Do not load a construction taxonomy for a
self-contained page-content or markup-repair task.

| Requested artifact | First reference | Use when | Completion boundary |
| --- | --- | --- | --- |
| Native page or post structure | [ASSEMBLE.md](references/ASSEMBLE.md), then [GUIDE.md §5–6](references/GUIDE.md) | You are inventing a page section and have no authored HTML whose styling must survive. Run `npx -y block-runner@0.9.7 assemble - --json` with an intent tree. | Valid native page `post_content`, delivered to the agreed destination. |
| Page or post content from authored design HTML | [GUIDE.md §4](references/GUIDE.md) | The supplied source is authored HTML; use `npx -y block-runner@0.9.7 convert - --json` when its CSS matters. | Valid native page `post_content` plus reported fallbacks and styling limits. Never treat frontend-scraped rendered HTML as authored input. |
| Reusable, named static registered block source | [AUTHORING.md](references/AUTHORING.md) | The requested result is a static `namespace/slug` block in code. | Confirmed source at its exact retained destination; build, integration, and WordPress proof remain separate. The complete plan in [AUTHORING-PLAN.md](references/AUTHORING-PLAN.md) is an advanced route, not a prerequisite. |
| Custom PHP renderer or editor behaviour in an existing project | [GUIDE.md §1.1](references/GUIDE.md) | Static generation cannot satisfy the requested component. | Continue in project-owned code; retain a useful native subtree only when it genuinely helps. Inspect [CONSTRUCTION-PATTERNS.md](references/CONSTRUCTION-PATTERNS.md) only when project facts needed for that implementation are missing. |
| Supplied block markup to repair or check | [GUIDE.md §5](references/GUIDE.md) | Markup already exists and must be safe to save. | `validate` → `fix` → `validate`; do not save a hard-invalid result. |

If “reusable section” does not say whether it is page `post_content` or a named registered source
block, ask that one artifact question before writing. Do not use this skill for unrelated WordPress
administration, non-WordPress HTML, or frontend-scraped HTML presented as source.

## Discover only missing project facts

For a component that belongs in an existing project, use [GUIDE.md §0](references/GUIDE.md) after
the artifact route is clear. Reuse established facts and inspect only the relevant source and site
context needed for this change. Existing-plugin integration needs inspection; a self-contained
paragraph repair does not. Use relevant facts to recommend reuse, supported generation or a
developer handoff. Recognizing a route does not add generator support. Ask only for choices that
the request and repository do not answer; use structured questions if your harness supports them,
otherwise ask in plain language.

## Generator boundary and continuation

- **A generated registered-block plan is declarative only.** Do not use React/JSX, PHP, a complete
  `block.json`, generated CSS, or `<!-- wp:… -->` delimiters as a substitute for that generator.
  Its model proposal makes reviewable semantic choices; deterministic code produces the executable
  files. See `references/AUTHORING.md` for the full proposal and confirmation contract.
- **Continue project-owned work normally when static generation does not fit.** If the component
  needs a custom PHP renderer or editor behaviour, inspect its project contracts and implement that
  code in the project. Do not generate a static shell that will immediately be replaced, and do not
  require later regeneration of ordinary project-owned source. Retain any useful native subtree from
  `assemble` or `convert`, and state precisely what Block Runner contributed. For example: “Block
  Runner cannot generate this custom renderer and editor. I’ll implement those in the project and
  use its supported helpers where useful.” See `references/GUIDE.md` §1.1.
- **Finish the job.** Deliver page markup or source to its agreed retained destination, never a
  temporary folder. Explain remaining wiring and unverified checks; see `references/AUTHORING.md`
  and `references/GUIDE.md` §6. For page content, paste through **Options ⋮ → Code editor**
  (`Ctrl+Shift+Alt+M`), not the visual editor.
- **When you produce markup and no destination is agreed, the reply is the delivery.** Put the
  complete markup in the reply before you summarise it; a file you wrote along the way is where the
  generator put its output, never where the job ended. Do not state a block count, a validation
  verdict or paste instructions for markup the reply does not contain: a confident description of
  output the user cannot see reads as success and is the one failure they cannot spot.
- **Prefer `--json` for automation.** Text output includes concise reasons and selected repair
  context, but JSON preserves the complete machine-readable report.
- **Never hand-write `<!-- wp:... -->` markup.** That is how invalid output happens. Describe
  structure instead and let `assemble` build it.
- **A `core/html` fallback is not a success.** It means that part is an uneditable blob. Check
  the report and tell the user.
- **If the CSS matters, use `convert`, not `assemble`.** An intent tree carries structure and
  content, not styling. Ask the user rather than silently flattening their design.
- **Name the proof claim and retain its receipt.** Headless markup checks do not establish custom
  PHP, custom controls, frontend behaviour, or editor persistence. See `references/GUIDE.md` §1.1
  and `references/AUTHORING.md`.
- **Passwords go in `--wp-app-password-env <NAME>`, never in argv.**
- **It is an assist, not a gate.** If the tool is unavailable, fall back to your own checks and
  say so — never block the user on it.

Block structure rules, the full node schema and per-section mappings are in
`references/ASSEMBLE.md`. Token and media resolution, exit codes, and failure posture are in
`references/GUIDE.md`.

From courtneyr-dev/glean-skills-public, GPL-2.0.

More from courtneyr-dev/glean-skills-public