Help us improve
Share bugs, ideas, or general feedback.
From wp-spec-to-goal
Convert a WordPress plugin or feature idea (even a vague one) into a Codex /goal-ready bundle — GOAL.md, VERIFY.md, PROGRESS.md inside goals/<slug>/ — with wp-env + playwright-cli + wp-eval verification baked in. Asks clarifying questions in focused batches (each with options + recommendation + reasoning), reaches 95% confidence, optionally scaffolds a missing plugin folder + .wp-env.json + package.json + AGENTS.md, and emits a tailored /goal command. For new WP plugin or feature work, not bug fixes or non-WordPress projects.
npx claudepluginhub nathanonn/agent-skills --plugin wp-spec-to-goalHow this skill is triggered — by the user, by Claude, or both
Slash command
/wp-spec-to-goal:wp-spec-to-goalThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn a rough WordPress plugin or feature idea into the three files Codex `/goal` needs to drive autonomous implementation:
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Explores codebases via GitNexus: discover repos, query execution flows, trace processes, inspect symbol callers/callees, and review architecture.
Share bugs, ideas, or general feedback.
Turn a rough WordPress plugin or feature idea into the three files Codex /goal needs to drive autonomous implementation:
goals/<slug>/
GOAL.md what done looks like (full WP plugin template)
VERIFY.md how /goal proves it's done (wp-env + playwright-cli + wp-eval, folded in)
PROGRESS.md the audit trail /goal will populate
The skill optionally scaffolds a missing plugin (plugin folder + .wp-env.json + package.json + AGENTS.md) and prints a tailored /goal command at the end.
A full multi-prompt workflow kit is overkill for plugins or features that fit in one or two goal slices. This skill collapses the "spec → goal trio" hop into a single guided conversation that:
It does not replace the multi-prompt kit when shipping a complex plugin from a long requirements doc. Use the kit for big builds; use this skill for the small-to-medium ones — and "small to medium" is genuinely small to medium, not just trivially simple.
goals-plan.md.goals/<slug>/./goal command + a short "how to run" note.Never write any files until confidence on what's about to be produced is at 95%+.
Before asking the user anything, inspect the cwd. The point is to ground recommendations in reality so questions don't waste the user's time on things already settled by the project state.
Look for:
.wp-env.json at root → wp-env is wired; note the port (default 8888)composer.json at root or in plugin folder → existing PHP project structure / namespace conventions<candidate-slug>/<candidate-slug>.php → existing plugin to extend rather than creategoals/ folder present → previous goal runs; pick a non-conflicting <slug> if needed.claude/skills/playwright-cli/SKILL.md available → playwright-cli skill is reachablepackage.json at root mentioning playwright or playwright-cli wrapper scriptsAGENTS.md present → respect existing conventions; surface them in scope decisionsprotocols/run_goal_tests.md → user already runs the canonical verification protocolUse this to inform Step 3 recommendations. Skip questions that the probe already answers (e.g., don't ask "should we wire wp-env?" if .wp-env.json is present — only confirm the port).
Read the user's spec and decide whether it fits one goal or wants to be split. The spec is multi-goal-shaped when any of these hold:
If multi-goal, surface it before any other clarifying questions:
This spec looks like it could be 2-3 separate goals. I can either generate one combined goal or write a
goals-plan.mdand scaffold the first slice. Which do you prefer?
If the user picks split, write goals-plan.md at the project root with a numbered list of proposed goals (each with a 1-2 line description), then ask which slice to generate first. Re-run the skill later for the next slice.
If single, continue.
Use the AskUserQuestion tool when available. If it isn't (older harness, plain chat, etc.), fall back to natural-language Q&A in chat with the same shape: 2-4 questions per round, each with 2-4 options, with the recommended option first and labeled (Recommended), plus a one-line reason for the recommendation.
Aim for ≤3 rounds total. Skip any question already answered by the spec or the probe.
Sample questions to consider (only ask the ones not already settled):
<slug>/ at project root (matches the wp-env + clean activation pattern). For features inside an existing plugin, default to that plugin's folder..wp-env.json is missing, ask whether to scaffold one with the plugin mapped in.Only ask the ones not obvious from the spec.
manage_options unless the user explicitly says public)wp-config constant / hard-coded? Recommend based on use frequency and audience.After each round, ask: "if I started writing files now, what could go wrong because of something I don't know?" If the answer is "not much," proceed. Otherwise, ask one more focused round.
If 3 rounds in and confidence is still under 95%, the spec might genuinely need a longer conversation or a different skill — say so to the user rather than guessing.
If the probe found missing pieces and the user agrees to scaffold, create only what they confirmed. Default missing-pieces set:
<slug>/<slug>.php — plugin header + activation hook + autoload bootstrap<slug>/composer.json — PSR-4 stub mapping the chosen vendor namespace to src/.wp-env.json — at project root, mapping the plugin folderpackage.json — at project root, with playwright-cli install hints and npm test / npm run lint placeholdersAGENTS.md — at project root, listing the stack, conventions, and the canonical commands /goal should run.gitignore — at project root, covering wp-env state, deps, OS/editor noise, and per-goal test artifactsTemplates for these files are in references/scaffold-templates.md. Read that file when scaffolding.
If any of these already exist, do not overwrite. Confirm with the user first; default to leaving the existing file alone and noting the conflict in chat. For .gitignore specifically, prefer offering to merge missing lines into the existing file rather than overwriting — .gitignores tend to grow project-specific entries that the user wants to keep.
Generate three files at goals/<slug>/. The full WordPress templates live in:
references/goal-template.md — full GOAL.md template (objective, source of truth, scope, allowed files, user stories, business rules, security, definition of done, completion audit, stop conditions)references/verify-template.md — full VERIFY.md template, with wp-env + playwright-cli + wp-eval folded in (no separate test_plan.md)references/progress-template.md — initial PROGRESS.md skeletonRead these reference files when generating. Substitute placeholders with everything the user confirmed in Step 3 and the project state from Step 1.
Filling rules:
{{...}} markers for two different things:
{{Plugin Name}}, {{slug}}, {{AC ID}}, {{description}}) — these describe content the skill must fill in now. Replace every spec placeholder with a concrete value derived from Step 3 answers and Step 1 probe state. Never leave one in.| | |), not as {{...}}. If you ever encounter {{cmd}}, {{note}}, {{file / test / output}}, or similar inside an example evidence table, that's a stale template signal — replace those cells with empty strings before writing the file. /goal will populate them later.Not applicable. plus a one-line reason rather than deleting the section — /goal's completion audit expects the section to exist.AC-001.1. The audit table in GOAL.md and the evidence table in PROGRESS.md reference these IDs.manage_options and out-of-scope explicitly excludes public access.{{ outside of code-fenced template-instruction comments. If you find any, you missed something — fix it.npx wp-env run cli .... Never emit a bare wp ..., composer ..., php ..., or phpunit ... — those run on the host's PHP/MySQL, not the wp-env container, and silently produce wrong results. The carve-out is non-WP tooling: npm, node, npx, playwright-cli, and git stay native. Before writing each command, ask: "is this tool inside the wp-env container?" If yes, prefix with npx wp-env run cli. The same rule is documented in the generated AGENTS.md (see scaffold template's "Canonical command pattern" section).VERIFY.md (Setup prerequisites + Environment Assumptions) and AGENTS.md (Harness sandbox section) both surface this — keep those notes intact when filling templates, and don't assume an unsandboxed environment when writing verification commands. If the user has flagged a specific harness or sandbox during Step 3, mention it in the relevant note; otherwise keep the warning generic.wp eval-file runs inside the wp-env container and can only see files mounted into it. The plugin folder <slug>/ is mounted at /var/www/html/wp-content/plugins/<slug>/; the goals/ directory is not. So when generating PHP-internal checks for VERIFY.md, place each test script at <slug>/tests/goal-checks/<goal-dir>/p-XXX.php (where <goal-dir> is the directory under goals/ for this goal — for a single-goal repo, that's the same as <slug>; for multi-goal, it's the slice name like 01-foo). The wp eval-file invocation in VERIFY.md must reference the container-relative path: wp-content/plugins/<slug>/tests/goal-checks/<goal-dir>/p-XXX.php. Never write wp eval-file goals/... paths — the container can't reach them. Browser test artifacts (playwright-cli screenshots, traces) stay under goals/<goal-dir>/test-artifacts/ because they're produced and consumed on the host.For VERIFY.md specifically:
.wp-env.json is missing or playwright-cli isn't installed, prepend a "Setup prerequisites" section listing what to install and how. Don't block — write the rest of VERIFY.md as if those tools will be there.composer.json and package.json for real script names before listing composer/npm scripts. Don't list scripts that don't exist.{{slug}}/composer.json get emitted as npx wp-env run cli composer --working-dir=wp-content/plugins/{{slug}} <script>, never as bare composer <script>. WP-CLI calls always go through npx wp-env run cli wp .... Only npm/node/playwright-cli invocations stay native.playwright-cli block with the session name goal-<slug> and concrete steps (host-side). If wp-eval is the answer, include the npx wp-env run cli wp eval / wp eval-file snippet inline.After writing the files, print this in chat (verbatim layout, with <slug> replaced):
Generated:
goals/<slug>/GOAL.md
goals/<slug>/VERIFY.md
goals/<slug>/PROGRESS.md
To run with Codex /goal:
/goal Complete goals/<slug>/GOAL.md. Use goals/<slug>/VERIFY.md as the verification contract. Update goals/<slug>/PROGRESS.md continuously. Treat uncertainty as incomplete.
How to run:
1. Open Codex inside this repo: codex
2. (Optional) /plan Read goals/<slug>/GOAL.md and VERIFY.md and propose an implementation plan.
3. Paste the /goal command above.
4. Review changes via `git diff` before committing.
If the skill scaffolded files in Step 4, list those above the goal trio under Scaffolded:.
If the skill wrote a goals-plan.md in Step 2, also append:
Next slice:
Re-run wp-spec-to-goal with: "next slice from goals-plan.md"
For every clarifying question, a strong recommendation is the difference between a 30-second answer and a 5-minute one. Heuristics:
composer.json).manage_options unless explicitly stated public. Nonces required for state-changing GETs/POSTs.Always explain why in one sentence so the user can override with confidence when their context differs.
Stop and ask the user instead of guessing if:
<slug>/ already exists)./goal's job./goal's job./goal directly with a bug-fix-oriented goal.