Prototype a WordPress plugin

A prototype is throwaway code that answers a question. This one answers:

Does this specified plugin hold together as a product?

Not "does this logic feel right?" and not "what should this look like?" Those are different prototypes. A state machine with no WordPress surface wants a throwaway terminal app that re-renders the whole state after every keystroke. Visual variations on one component want several structurally different renderings of one route, switched from a floating bar. If the question is really one of those, say so and build that instead — this skill is the wrong shape for it.

This skill applies when there is a WordPress plugin, an admin or front-end surface, and an intent to evaluate behaviour before implementing it.

What this needs

No Node version, no dependency install, no build step. The prototype is classic scripts served as files.

Three layers

Every prototype is built as three separable layers. Keeping them separate is what makes two-thirds of the work copyable and the last third portable.

The engine is the single resolution path. Every surface consumes it; no surface re-implements a rule that belongs in it.

The kit and every measured claim in these documents come from the source run — a 4,916-line WooCommerce gallery-plugin prototype built from a written spec. Every file in this skill uses that phrase for it.

Modes

State the mode before building and put it in the README. The user steers the budget — never size the work silently.

Focused mode exists because neither of the other two prototype shapes serves "build me a working WordPress settings screen."

The build

Twelve phases. The order is a dependency graph, not a preference.

P0 · Assess the spec

Read the spec in full. The questions in P1 are only visible to someone who has read the whole document.

Run a pre-flight and report what is present and what is absent — state the consequence for the build, and stop there. Deliver the report before building anything:

Full-coverage needs all six of: an entity model with fields · a resolution or precedence rule where more than one source of truth exists · enumerated settings with types and defaults · the failure states that matter · at least one worked example with stated expected output · explicit non-goals.

Below that bar, say so, offer focused mode, and wait for the answer. Settling the mode is not a shape question — the round-trip limit at the foot of this file counts shape questions only. Rule IDs, acceptance criteria and state tables are upside, not requirements.

No worked example anywhere? Propose one — inputs and expected output — and get agreement before building. A prototype with no assertable expected output cannot be verified, only admired.

No spec at all? State the gap and offer the fork: write a thin spec first — problem, solution, user stories, implementation decisions, out of scope — or build a narrow prototype answering one question. If the user proceeds anyway, drop to focused mode, elicit only the six-item list inline as a handful of questions, and record every assumption at the top of the README so invented requirements stay visible as inventions. Never present an assumed requirement as a specified one.

Honour stated non-goals as constraints. Leave a deferred feature unimplemented and exercise its absence — implementing it silently short-circuits the fallback rule the spec does define.

Done when: the pre-flight report is delivered and the mode is named.

P1 · Ask

Escalate shape. Decide construction.

One batched question round — AskUserQuestion where the harness provides it, otherwise a single numbered message — after reading the spec and before writing any code. Three questions — four in focused mode. Every option carries a recommendation and its reasoning; the recommended option is listed first and marked.

1. Fidelity — WordPress admin lookalike, or neutral prototype UI? Lookalike reproduces admin chrome faithfully so the artifact doubles as a visual spec, and costs the full spine plus overlay (505 lines of CSS). Neutral is much cheaper and useless as a visual reference. This has the largest blast radius of anything asked here, and nothing in a spec or a repo predicts the answer.
2. Debug surface — a live rule/state inspector, a state-only inspector, or neither? If the answer is neither, state in one line that this overrides the standing rule that a prototype renders the full relevant state after every action, so the override is a recorded choice rather than an omission — then honour it, and leave it honoured. Rule IDs still go into source comments either way (P5): declining an on-screen surface never costs traceability.
3. Overlay — detect it first, from plugin headers, composer.json / package.json, required-plugin statements in the spec, and domain vocabulary (product, variation, cart). Present the detection as the recommendation with its evidence, for the user to confirm or correct. Asked rather than inferred because a wrong guess means rebuilding the most expensive layer, and a third question inside a round that is already happening costs nothing. Only WooCommerce ships as an overlay — where none applies, the answer is plain WordPress admin and only the spine is built.
4. Surfaces (focused mode) — which surfaces are in scope. Build nothing outside them.

After this round, do not ask again unless proceeding under any assumption would be unsafe or would make the work useless if wrong. Construction questions — libraries, file layout, naming, styling — are answered by the table at the bottom of this file.

Done when: three (or four) answers are in hand, from one round trip.

P2 · Scaffold → kit/KIT.md

Copy the spine into the prototype root — a directory whose name identifies it as a prototype, inside the repository the plugin belongs to, at the repo root or beside the module it concerns, never inside the plugin's own source tree. Decide it here, because this is where the copy happens; the Capture section of OUTPUTS.md reasons about the choice at P10.

Copy the overlay if the answer to question 3 named one. Wire up the four configure calls, uncomment the four prototype <script> tags in index.html, and delete the placeholder boot block beneath them.

The shell does not stand up on kit files alone. WP.configure() resets the store as it runs, so it throws without a fixtures function, and the router renders an error notice with no route registered. Write a throwaway stub fixture function and one stub route — scaffolding, not spec work, replaced by P4 and P7.

Done when: the shell serves from one command with an admin bar, a menu and a routed empty screen, and the placeholder boot block is gone. A page reading "no prototype scripts are wired up yet" is that block still in place — the index.html edit at the top of this phase, not a boot bug.

P3 · Media → kit/RECIPES.md

Before fixtures — a fixture pointing at a missing file is invisible until render.

Done when: every file the fixtures will reference exists, at varied aspect ratios.

P4 · Fixtures → BUILD.md

Done when: every spec worked example is a fixture verbatim, the adversarial checklist is covered, and the fixture pre-flight passes all three checks.

P5 · Domain engine → BUILD.md

Done when: the engine holds every rule the mode covers, contains no DOM reference, and cites spec rule IDs in source comments with none invented.

P6 · Verify the engine → VERIFY.md

A distinct phase, before any screen exists. Do not fold it into P9.

Done when: every worked example, state table, validation rule, precedence level and derived-key stability check has been asserted with measured values quoted.

P7 · Screens → BUILD.md

Done when: every screen and meaningful sub-state has a URL, and the mode's surfaces are built.

P8 · Driver panel → DRIVER.md

Done when: every baseline state the spec mentions is drivable, and each has an observable effect on a default route.

P9 · Verify the interface → VERIFY.md

Done when: both measurement and visual review have run, every route loads with zero console errors, and every spec acceptance criterion has been exercised.

P10 · Document → OUTPUTS.md

Done when: the README carries all seven sections, a coverage table organised by the spec's own sections, and three honest-limits lists.

P11 · Porting note → OUTPUTS.md

Required in full-coverage mode, optional in focused mode.

Done when: the engine is mapped to its intended PHP home, and rules validated by measurement are distinguished from rules implemented by reading — or, in focused mode, the phase is declined out loud rather than skipped quietly.

Decided without asking

Each of these is settled so that a future change is a deliberate revision rather than drift.

Mark the prototype as throwaway in the README title and in a header comment in every source file.

What failure looks like

The prototype has failed, however good it looks, if it produces:

• fidelity that makes invented requirements look specified — the worst outcome available here;
• a coverage claim the verification did not establish;
• no assertable expected output anywhere;
• a driver panel indistinguishable from the plugin's own UI;
• a rule ID in the source that does not exist in the spec;
• more than one round trip of shape questions.

Credit

Derived from Matt Pocock's prototype skill (github.com/mattpocock/skills, skills/engineering/prototype/), which supplies this skill's framing and its throwaway / one-command / in-memory / no-polish / surface-the-state / capture-it rules. The WordPress-specific build — the twelve phases, the spine/overlay/engine split, the driver panel, the asset kit and the two-pass verification — is new here. Matt's skills are MIT licensed.