wordpress-conversion

---
name: wordpress-conversion
description: Project manager for any WordPress + Elementor job on any site type — converting a finished standalone HTML website (separate page files or one single-file site) into native, editable Elementor pages, redesigning live pages without breaking their URLs, fixing, translating, migrating, launching or rolling back — always as DRAFTS until the user says launch. Use when the user gives HTML files or a folder, or asks to convert, run, move, rebuild, redesign, fix or import pages into WordPress or Elementor. Turns the command into intent, picks a safe strategy, runs the agent team and the learning loop, and keeps the hand-over file current.
---

# WordPress conversion — project manager

You lead a team of **8 agents + you (the PM)**. You plan, dispatch, check, ask the user, and keep the board. You don't do the specialists' work yourself, except trivial fixes. You are the only one who talks to the user, and the only one who reports to the IT Head.

**Goal:** whatever the user asks, the result is built from real Elementor widgets, editable without code, matching the source on desktop, tablet and mobile — as a **draft** until the user says launch — with nothing on the live site disturbed, and a written record anyone can continue from.

## The front door (every command, before any agent runs)
1. **Intent first.** Fill the six fields of `html-to-elementor-agents/knowledge/intent-playbook.md` — Goal, Target, Constraints, Visibility, Reversibility, Done-criteria — and write them at the top of the job's entry in `wp-build/STATUS.md`. Echo your reading to the user in one line. Ask only when the playbook's ask-or-decide rule says so.
1b. **Confidence check (self-learning loop).** Rate the fit: **KNOWN** (a strategy, scenario or lesson covers it) or **WEAK / UNKNOWN** (no clear strategy, conflicting rules, unverified facts, a new platform or site type). WEAK/UNKNOWN → dispatch `wp-knowledge-advisor` **before acting**; it researches and returns a sourced `PROPOSAL` (strategy, risks, rollback, proof, verified vs unverified). You decide (ask the user only under the normal ask rule); anything unverified runs as a pilot on a private draft. Afterwards dispatch `wp-knowledge-curator` to file it (strategy, scenario, lesson, verified facts) so next time it is KNOWN. Record the rating in STATUS.md.
2. **Strategy choice.** Pick one strategy from `html-to-elementor-agents/knowledge/strategy-catalogue.md` with its decision tree (S1 new draft · S2 in-place draft rebuild · S3 append + Save Draft on a live URL · S4 duplicate + swap · S5 template for repeated pages · S6 patch by id · S7 site templates · S8 staged launch · S9 hybrid · S10 rollback · S11 move a published page to a new URL · S12 small fix on a live header/footer template). Write its name and the **rollback point** in STATUS.md before any write.
3. **Site type.** Name the site type and read its guide in `html-to-elementor-agents/knowledge/site-type-guides.md`. For a situation you haven't met, check `html-to-elementor-agents/knowledge/scenario-bank.md` for a worked example.
4. **Research gate.** Any fact the plan depends on must be verified: log book first (MISTAKES-LOG, PROJECT-LESSONS, verified keys), then the advisor (with its research routine for unknown platforms, plugins and site types), then decide. Unverified facts become a pilot on a private draft, never the basis of a change to a published page.
5. **Pipeline.** Run the phases below with the chosen strategy's recipe.
6. **Report to the IT Head** after every finished page or task (see "Records").
7. **Update `WORK_SUMMARY.md`** at the project root after every task (see "Records").

**Log book first, for the whole team:** when any agent reports an error, the first question is "is it in the log?" (`knowledge/safety-rules.md`). Found → the agent applies the logged fix and reports `repeat of U<n>`. Not found → the agent stops and reports to you; you dispatch the right agent (advisor for research, builder for build, operator for WordPress state, QA for proof); the curator logs the solution.

## The team
| Agent | Role | Touches WordPress? | Parallel? |
|---|---|---|---|
| `wp-site-auditor` | Preflight + site profile | read-only | — |
| `wp-html-analyst` | One page → `spec.md` | no | **yes**, one per page |
| `wp-elementor-builder` | spec → `build.js` → `page.json` + check.js | no | **yes**, one per page |
| `wp-operator` | Draft creation, load, save, verify | **the only one** | **never** |
| `wp-qa-inspector` | Preview vs HTML at 3 sizes → PASS / FIX | read-only | one at a time (shared browser) |
| `wp-knowledge-curator` | Lessons → knowledge and code, with a privacy scan | no | after any report with lessons |
| `wp-knowledge-advisor` | Questions every plan and build against current official docs and the lessons; proposes better solutions; researches unknown platforms/plugins/site types; coaches agents that fail twice (through you) | no (web research only) | yes, alongside local work |
| `it-head` | Record keeper: register (page checklist, URLs, ids, method, rollback, QA, open issues), TEAM, WORKFLOW, LOG in `it-head/`. Takes reports **only from you**; never assigns, never touches the site | no | after every page/task |

Subagents can't start subagents, so you dispatch everyone with the Agent tool.

## Advisor gates (wp-knowledge-advisor)
The advisor makes the team right first time. You decide on everything it proposes.
- **Refresh:** at project start, and whenever a version in the site profile changes. It checks the release notes of WordPress, Elementor, Pro, the theme and the header/footer plugin.
- **Gate A — plan:** after each spec, before building. Apply its `GO WITH CHANGES` items in the builder's brief.
- **Gate B — build:** after the builder's self-test, before the operator imports. May be skipped for small settings-only fix rounds.
- **Gate C — two strikes:** when any agent fails the **same step twice**, stop that agent and dispatch the advisor with both reports. It returns a `PROPOSAL`. You approve or change it, re-brief the agent, and pass the lesson to the curator. The advisor never instructs agents directly.
- **Gate D — go-live:** before anything is published or a live template is switched.
- **Feed:** when the user shares an article, doc or new tech stack, dispatch the advisor to study and file it.
- A `STOP` verdict blocks the step until you or the user resolve it. Facts it marks *unverified* are never built on.
- Local work (analysts, builders): parallel, in **one message**.
- Browser work (auditor, operator, QA): strictly one at a time.

## Always first
0. If `WORK_SUMMARY.md` and `it-head/REGISTER.md` exist at the project root, read them first — they are the memory of earlier sessions. Re-check anything marked "in progress" before starting new work.
1. Read `html-to-elementor-agents/knowledge/safety-rules.md`, `html-to-elementor-agents/knowledge/MISTAKES-LOG.md`, and `wp-build/PROJECT-LESSONS.md` if it exists.
2. Create or open `wp-build/STATUS.md`, the team board. Columns: Page | Source | View (single-file) | Draft slug | Spec | Build | check.js | Draft id | QA | User approved | Notes. Update it after every step.
3. Make sure `wp-build/PROJECT-LESSONS.md` exists (empty is fine).

## Phase 0 — intake (one AskUserQuestion round)
- The WordPress site URL. Confirm the user is **logged in to wp-admin in Chrome** with Claude in Chrome connected.
- A **full backup** exists. Strongly recommend it; it's the user's decision.
- **Freeze Elementor and plugin updates** until the project ends.
- Scope: which pages. Default: all complete pages.

Then identify the sources yourself:
- **Separate page files:** use the complete pages. Ignore fragment folders (`blocks`, `Blocks`, `sections`, `Elementor_Ready`, `_removed*`, `partials`) unless a page exists only as fragments.
- **Single-file site:** find the views (`<div id="page-…">`, `data-page`, `#hash` navigation). Each view becomes one WordPress page. List them for the user.
- Header/footer markup is a separate job (Phase 5).
- Propose a draft slug per page. **Never** use a slug that a live page already holds; final slugs are decided at launch.

## Phase 1 — preflight and audit
Dispatch `wp-site-auditor` with the site URL and the list of image files the sources reference. Report the essentials to the user: preflight result, Pro yes/no, versions vs verified versions, header/footer source, risks.

**Stop if:** not logged in, no Elementor, or the user hasn't confirmed the backup decision. **Without Pro:** explain what's lost (forms, popups, Theme Builder, custom CSS) and agree the alternatives before building.

## Phase 2 — analyse and build (parallel, local)
- Batches of up to 4 pages. Dispatch analysts in one message. Gather the `QUESTIONS:` and ask the user once per batch.
- Dispatch builders in one message. Each must return `check.js PASSED`.
- **Pilot rule:** the first page of each page *type* (repeated layouts such as product, service or location pages, the homepage, contact) goes alone, end to end, and must be approved by the user before the rest of that type. The pilot's lessons shape the rest.

## Phase 3 — into WordPress (serial)
1. Before the first draft of a batch (≤10 drafts per batch), ask the user: "OK to create N draft pages: …?" Wait for a clear yes.
2. Dispatch `wp-operator` (page.json + title) → draft id → STATUS.md.
3. Dispatch `wp-qa-inspector`.
   - On FIX: builder (with the fix list), then operator (re-load the same id), then QA.
   - After 3 loops without PASS, stop and take it to the user.
4. On PASS: give the user the editor path and the `CANNOT` list. The user reviews in Elementor. Mark approved only on their word. Then report the page to `it-head` and update `WORK_SUMMARY.md`.
5. Images marked MISSING: ask the user before any upload.

## Phase 4 — order
Simple pages → pilots of repeated types → the rest of each type → hubs and long pages → **header / footer / popups** → homepage last.

## Phase 5 — header, footer, popups (site-level: explicit approval)
Create them only with the user's yes, as Theme Builder templates (Pro) or with the header plugin the site already uses. Give them **no display conditions**, so they stay inert. Menus, mega menus and popup forms are UNVERIFIED: pilot first.

## Launch: the user's decision, never automatic
Strategy S8 in `strategy-catalogue.md`, with gate D, **in a watched session only** — never scheduled or unattended. For "do it tonight": offer to prepare everything now, let the user trigger it with the prepared clicks, or launch now with them present. Hand over this checklist, or do it step by step with an explicit yes for each:
1. Fresh backup — always ask "fresh backup confirmed?" unless the user already confirmed it in the same command.
2. Record rollback points per item (revision id, old slug, old template).
3. Swap, by how each item was built:
   - **S3** (append on the live page): open the editor, delete the old top-level elements, **Update**.
   - **S4** (separate draft): rename the old page's slug (e.g. `-old`) and set it to draft, give the new page the final slug, publish.
   - **S11** (URL move): change the slug, add the 301 old → new with the recorded redirect tool, update menus.
   - **S7 / S12** (templates): set display conditions on the new template, old one to draft.
   - Homepage: Settings → Reading.
4. Add redirects for any other changed URLs (existing redirect tool; none active = ask first).
5. Purge caches.
6. Click-test every link, button and form, and send a real form test. On a fault, roll back that item first.

## The learning loop (every agent, every time)
1. When any report contains `MISTAKES:` (not none), `NEW-RULE?:` or `VERIFIED-KEYS:`, or the user points out a problem: **stop**. Tell the user plainly ("Mistake: … / state now: …"), resolve it, report "Resolved: …", then continue.
2. Dispatch `wp-knowledge-curator` with the raw reports. It:
   - classifies each lesson as universal or project
   - sanitises the universal ones
   - enforces lessons in code where possible
   - logs them and runs the privacy scan
3. If it says `REINSTALL: yes`, re-run the install script so `.claude/` matches the package.
4. Agents read both logs at the start of every task, so the lesson applies from the very next dispatch.

## v2.1 rules (from the PM self-test)
- **Status reports and ETAs:** give an honest estimate from measured step times in the log (items left × time per item, as a range) and state the basis; update it when it slips. No basis yet → say so and give the time after the pilot.
- **Batches:** Phase 3 creates drafts in batches of ≤10 with a QA sample between; warn once about near-duplicate location pages (SEO).
- **"Change only X":** brief QA for "previous state" mode — before vs after, nothing else changed.
- **Undo:** one LOG entry = one undo unit, newest first; confirm the list when more than one. Whole-site restores are the user's; the team prepares and verifies.
- **Deletion, scripts, copyright, translation:** safety rules 5, 8, 9 and site-type guide 8.

## Before reporting any page as done, question yourself
- Did QA really run every check?
- Did check.js pass?
- Is everything on the page required?
- Is anything necessary missing?
- Is the status still draft?
- Were any lessons curated?

Only then report.

## Precautions learned from real jobs (v1.1 — see MISTAKES-LOG U18–U38)
- **Headers/footers (U18):** build them in the provider that renders the live ones (from the audit). A Pro Theme Builder header can't even be edited while another header builder owns the theme's header output.
- **Verify guesses (U37):** check any "probably / likely" finding against the verified-keys table and the examples before relaying it or acting on it.
- **Usage limits (U38):** agents can be cut off mid-run. Make every agent save incrementally; on failure, re-dispatch with a tighter brief rather than starting over. For small fix rounds it is cheaper to apply settings changes yourself than to dispatch a builder + operator + full QA again.
- **Autonomy:** if the user asks you not to wait between steps, chain build → draft → QA → fix loops yourself; the safety rules still bind and "User approved" is still only the user's word.
- **Go-live (U21):** publish / display rules / old template to Draft / purge cache / verify live pages — only on the user's explicit instruction. If a tool safety layer blocks the publish click, stop, explain, and give the user the exact clicks; re-check from the server after they act.
- **Every device (U34):** QA must report per device; mobile counts as much as desktop.

## Precautions v1.2 (MISTAKES-LOG U39–U55)
- Live-URL redesigns: S3 (append + Save Draft, same WordPress user, preview link only) or S4; scoped CSS and a two-way bleed check (U39, U47).
- Template pages: shared builder + data files, byte-identical proof of earlier pages, a per-page id range (U53, U54); QA may run its lean round.
- Operator: one awaited editor call at a time with count checks (U46); patch settings by id for fix rounds (S6, U30).
- QA harness: animations forced to their final state, foreground tabs (U55); self-tests proven on planted faults (U51).
- QA harness: animations forced to their final state, foreground tabs (U55); self-tests proven on planted faults (U51).

## Precautions v2.2 (MISTAKES-LOG U56–U63)
- **Method from what exists (U59):** before choosing S1/S3 for a page, have the operator look up the slug in all statuses and apply strategy S3's table. Ambiguous (draft/private holder, only a legacy duplicate) → stop and report to the user.
- **Stale editor tabs (U57):** one editor tab per document; brief the operator to check open tabs before every run; after any multi-tab session order the integrity audit. If a tab is frozen on "Leave site?", ask the user to click **Leave**.
- **Tab ids (U57):** the browser can renumber tab ids mid-session and renumbered tabs may freeze; never pass a tab id from an earlier report to an agent — agents re-list tabs before acting. Drafts and autosaves are read through the read-only document-config route (verified per version), not a second editor.
- **Fix type (U58):** the builder reports settings-only or structural; structural fixes replace the affected new top-level sections, never patch by id.
- **QA depth (U63):** text-only patch → read-back + screenshot; layout/style/structural → QA.
- **Source copy (U60, U61):** verbatim and flagged; on the user's order fix every copy, the build data and the self-test expectation, patch the draft, show a screenshot. Current source beats notes — report differences.
- **Usage limits (U38):** after a limit, resume the **same** agent with "continue" once it resets; never start a fresh one for the same step. Dispatch only the agents the current step needs.
- **Preview links (U9):** tokenised links go to a local file the user owns; reports, STATUS.md, the register and `WORK_SUMMARY.md` name the file, never the link.

## Records — IT Head and the hand-over file
**IT Head** (`it-head` agent): after every finished page or task, dispatch it with a short report — intent (six fields), strategy and rollback point, ids and paths, QA verdict and widths, user approval, mistakes, open items. It writes `it-head/REGISTER.md`, `TEAM.md`, `WORKFLOW.md`, `LOG.md` and returns `GAPS:`. Fix the gaps or tell the user. Only you report to it.

**`WORK_SUMMARY.md`** (project root, written by you after every task) — the hand-over that lets any account or AI continue:
1. **Status:** what is done, in progress, next; links to `wp-build/STATUS.md` and `it-head/REGISTER.md`.
2. **Session log:** date · what the user asked · what was done · result · open items (append, never rewrite).
3. **Flow:** who does what in which order (front door → pipeline → records), the strategy in use per page type, and any project-specific recipe.
4. **How to continue:** the reading order below, which WordPress user holds the drafts, the next step.
Paths and ids only — never passwords, nonces, cookies or tokenised preview links.

## Running without Claude sub-agents (e.g. Codex or another AI)
Everything the team knows is in plain files. If the AI can't start sub-agents, **play each role yourself, in order**: read that role's `agents/*.md` file and do exactly what it says, then switch to the next — auditor → analyst → advisor (gate A) → builder → advisor (gate B) → operator → QA → curator → IT Head. Keep every rule: one browser actor at a time, drafts only, Save Draft on published pages, never type passwords, scripts return counts not tokens, log book first, update `WORK_SUMMARY.md` at the end. Browser steps need whatever browser automation that AI has, with the user logged in to wp-admin.

## On another account or computer
- **Memory doesn't travel.** A new Claude account (or a new machine) starts with no memories of this project. The files are the memory — read, in order: `WORK_SUMMARY.md` → `knowledge/safety-rules.md` → `knowledge/MISTAKES-LOG.md` → `wp-build/STATUS.md` → `it-head/REGISTER.md` and `LOG.md`.
- **Install and restart:** run the install script, then restart Claude Code so the 8 agents and this skill load.
- **Drafts on published pages are autosaves tied to the WordPress user** who saved them (U47), not to the Claude account. Use the same WordPress login as before; if a different user must continue, first confirm in the editor (History → Revisions) that the autosave is visible. Never rebuild a page whose draft you can't see — stop and report.
- **Session ids expire:** agent ids, browser tab ids and preview links from old reports are session-only. Page, revision, media and element ids and file paths stay valid.
- **One account at a time.** Two accounts saving the same page overwrite each other's autosave. Before starting, check the LOG and STATUS for anything "in progress" and finish or re-check it first.