r/ProWordPress • • 10h ago

Honest dev feedback wanted: Separating WordPress core structure (parent theme) from visual "Skins" + using strict JSON schemas & phase protocols to keep AI coding agents from breaking architecture

0 Upvotes

Hi everyone,

I’m a solo designer and developer from Japan running a small studio. \*(Sorry in advance for my English—I’m using AI to help translate!)\*

I’m not here to promote anything or drop commercial links—I genuinely want to share an architecture and AI-assisted workflow I’ve been building for WordPress client work, and get honest feedback from fellow WordPress developers.

\### The Problem I Wanted to Solve
Over the years, I’ve had to rescue a lot of broken WordPress sites where multiple redesigns were stacked on top of each other—ending up with \`!important\` wars, broken skip links/keyboard focus, and layouts that break whenever the theme updates.

At the same time, when I started using AI coding agents (Cursor, Claude Code, Codex, etc.) for client sites, I noticed that without strict boundaries, AI tends to hallucinate custom CSS overrides, blur responsibilities between theme and plugins, or silently break baseline accessibility.

\### The Architecture I Built Around It
To solve both issues at once, I designed a strict separation model:

  1. \*\*Standardized Parent Theme (Core Structure & Baseline QA):\*\*
    \- Handles the shared WordPress foundation, security/update resilience, keyboard navigation/skip links, and structural baselines—so updating the core never breaks client-specific designs.
    \- \*(Note: The parent theme itself is a 100% free GPL classic theme listed on WordPress.org under \`Variable Thema\`.)\*
  2. \*\*Lightweight Child Themes ("Skins"):\*\*
    \- Each client site gets its own isolated Skin responsible \*only\* for visual layout and styling, governed by an explicit Parent-Skin responsibility contract.
  3. \*\*Structured Markdown & JSON Schema Protocols for AI Agents (Not Just Ad-Hoc Prompts):\*\*
    \- Instead of asking an AI to "build or migrate a site" freehand, I built a 20-phase execution protocol and a formal \*\*Phase-00 Diagnosis JSON Schema (\`diagnosis.schema.json\`)\*\*.
    \- Before writing a single line of theme code, the AI and human run a structured Phase-00 diagnosis (for either a greenfield build or legacy theme migration), classify ownership boundaries, and execute step-by-step through isolated build, migration, and QA gates (including No-JS and keyboard accessibility checks, plus a sandbox lab fixture for skin-switching and troubleshooting).

\### What I’d Love Your Honest Take On
As fellow WordPress builders:

  1. Does this strict \*\*"Parent Core + Isolated Visual Skin"\*\* split match how you manage long-term client maintenance, or do you prefer full block themes / FSE / custom starter themes from scratch?
  2. For those using AI coding agents in WordPress workflows: how are you keeping AI from making messy architectural shortcuts? Do structured JSON schemas and phase-by-phase Markdown guardrails resonate with how you work?

Would love to hear how you approach this in your own shops—any critical feedback is super welcome!