feat(cli): WordPress site generator for Studio Code (theme + companion plugin)

[draganescu]

Related issues

• No related issue linked yet.

How AI was used in this PR

This is an AI-assisted proof of concept for a larger Studio Code capability. AI helped generate the initial implementation, iterate on the generation pipeline, add focused tests, and resolve the latest origin/trunk merge conflicts. The current branch state has been reviewed locally enough for draft review, but this should still be treated as directional work rather than merge-ready production code.

Proposed Changes

What

Adds a WordPress site generator flow to Studio Code so a user can describe a site and have Studio produce a working local WordPress site from that brief. The flow can plan design directions, generate a block theme, add a companion plugin for behavior and custom data, seed pages and content, generate imagery, and validate the result.

Why

The goal is to make Studio more useful for first-draft site creation. Instead of asking the agent to hand-edit one file at a time, this gives it a purpose-built path for creating a coherent starting point that still follows WordPress conventions: editable block content, a presentation-focused theme, and behavior that survives a theme switch.

How

The branch adds a site-generator skill, generation helpers, agent tools, tests, and an eval harness around the workflow. The generated site is split into a block theme plus a companion plugin, with identifiers and manifest checks to keep generated templates, blocks, custom post types, taxonomies, and seeded content aligned.

The current state also includes fixes from live iteration:

• Guards against custom post type routing issues.
• Avoids archive recursion in generated templates.
• Skips dangling taxonomy references.
• Avoids relying on remote fonts.
• Uses a single-pool orchestration path for faster generation.
• Adds eval coverage for generated plugin and content contracts.

This PR is current with origin/trunk as of eb7ce03d via merge commit 11a08945.

Testing Instructions

Verification already run on the updated branch:

• ./node_modules/.bin/eslint --fix apps/cli/ai/skills.ts apps/cli/ai/system-prompt.ts
• corepack npm run typecheck --workspace wp-studio
• ./node_modules/.bin/tsc -p scripts/tsconfig.json --noEmit
• ./node_modules/.bin/vitest run apps/cli/ai/tests/system-prompt.test.ts apps/cli/ai/tests/skill-prompts-contract.test.ts

Suggested reviewer flow from a complete dependency install:

npm install
npm run cli:build
node apps/cli/dist/cli/main.mjs ai

Then authenticate with WordPress.com if needed and exercise the /site-generator flow against a throwaway local site.

Note: a full all-workspaces typecheck was attempted from the new worktree, but that worktree did not have its own dependency install. The CLI workspace typecheck and the root scripts TypeScript check passed.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[draganescu]

This for now is a one size exploration which tries to settle the best shape of porting some of the Telex learnings on site generation into agent friendly skills and tools.

Images don't generate because of the auth system on WPCOM for certain ai proxies which is not tied to user auth. The agent using the orchestrator command is still significantly slower than the Telex PHP orchestrator.

Finally, an area this exploration shed light on is that we need to have a wp build system bundled somehow so we don't npm install for every theme fresh. Right now the draft instructs generation as vanilla JS for blocks to avoid building.

[youknowriad]

Thanks for starting this, excited for some consolidation to happen. a few questions:

• how is generate_theme different than the current scaffold_theme (should they merge?)
• Some sites might not need plugins at all, do we always attach a plugin or only when needed?
• Do we need to use the slash command to generate a site, can't it be auto-invoked on user's prompt?

Reading your comment, it seems you're considering this as a PoC for the whole flow. I wonder how possible would it be to ship the corrections and each step separately as iterations. Maybe you're already considering this?

[draganescu]

Yes I am considering this a PoC and I'll push it as far as it gets until I get a site that just works from a prompt. Then we figure out details. Because once we have a working path we can architect it into pieces. That is non standard, I know, but these skills are very finicky to test standalone. Ideally, studio code will get what Telex didn't - an eval system - so we can confidently tweak these.

To your questions:

• no, ideally we don't need to use the slash command, it should auto invoke when user says "make a website", "build a theme" etc.

• the plugins are blocks, content model and content seeding. I think the orchestrator skill should give the user the option to opt out of any.

• theme generation vs theme scaffolding, one is a generation of a full theme the other is a setup for someone to build on top of. Yes, they should merge.

[youknowriad]

Most sites I think don't need a plugin (like mine) and would prefer just having core blocks. I think we can discuss these details later, but I'd prefer that we don't optimize for plugin heavy outputs.

[draganescu]

Site generation skills and tools

This branch intentionally keeps the site-generation surface inside ai/skills and ai/tools. The agent still owns conversation, review, and repair loops; the site generator is a tool-owned engine behind generate_site.

Full generation flow

flowchart TD
    A["User asks for a complete site"] --> B["Pi runtime starts Studio agent turn"]
    B --> C["Skill tool loads site-generator"]
    C --> D["site-spec resolves missing site details"]
    D --> E{"Use existing site"}
    E -->|"Yes"| F["site_info or list_sites"]
    E -->|"No"| G["create_site"]
    F --> H["start_site if needed"]
    G --> H
    H --> I["visual-design plus theme-architecture build spec"]
    I --> J["generate_design_previews"]
    J --> K{"User choice"}
    K -->|"Choose direction"| L["generate_site"]
    K -->|"Regenerate"| J
    K -->|"Stop"| Z["No site changes"]
    L --> M{"Review before apply"}
    M -->|"Yes"| N["guided mode apply false"]
    N --> O["Return manifest warnings STAGED_RUN_ID"]
    O --> P{"User approves"}
    P -->|"No"| I
    P -->|"Yes"| Q["generate_site stagedRunId apply true"]
    M -->|"No"| R["one-shot mode"]
    R --> S["Plan generate validate apply"]
    Q --> S
    S --> T["generate_image if needed"]
    T --> U["validate_and_fix_blocks"]
    U --> V["take_screenshot"]
    V --> W{"Rendered issues"}
    W -->|"Yes"| X["visual-polish inspect_design Edit or wp_cli"]
    X --> U
    W -->|"No"| Y["Optional audits preview export sync"]

Loading

Skills

Skill	Purpose	When used in full generation	Can user choice skip it
site-generator	Main workflow contract for complete local site generation.	Always for "build me a site" or "generate a theme/site" requests.	No, unless the user is not asking for full generation.
site-spec	Gathers site name, target site, and layout preference before creation.	When the prompt lacks site name or the agent needs to create/select a site.	Yes, if the user already named the site and target.
visual-design	Defines visual direction, tone, typography, color, and layout quality.	Before previews and whenever visual polish is needed.	Mostly no for polished generation; can be minimal if the user gives a strict design brief.
theme-architecture	Keeps the theme pure presentation and defines layout/content mode.	During spec planning and manifest generation.	No for full generation.
block-content	Rules for editable WordPress block markup and validation.	During generated content review and block fixes.	No for any block markup changes.
layout-patterns	Concrete block-theme layout patterns and gotchas.	Conditional when the chosen design needs specific layout patterns.	Yes, if the design is simple.
companion-plugin	Defines generated plugin behavior, CPTs, REST routes, and custom blocks.	Conditional when the spec needs behavior beyond presentation.	Yes, if the site is brochure-only.
data-persistence	Canonical pattern for forms and submitted data.	Conditional for contact, booking, RSVP, lead capture, reviews, or similar inputs.	Yes, if there is no submitted data.
wp-best-practices	PHP quality, escaping, sanitization, capabilities, and performance rules.	Conditional when companion-plugin PHP is generated or reviewed.	Yes, if no plugin PHP is involved.
plugin-recommendations	Chooses third-party plugins/blocks when core WordPress is not enough.	Conditional for ecommerce, LMS, events, forms, galleries, SEO/perf plugin choices.	Yes, if the generated site sticks to core + companion plugin.
visual-polish	Screenshot-driven rendered-DOM diagnosis and fix loop.	After generation if screenshots show layout, spacing, contrast, width, or interaction issues.	Yes, if the user stops after generation or screenshots are acceptable.
annotate	User points at rendered elements and leaves visual annotations.	Optional after screenshots when feedback is easier by pointing.	Yes, always optional.
need-for-speed	Frontend performance audit and optimization recommendations.	Optional after the site works visually.	Yes, always optional.
rank-me-up	On-page SEO audit and search recommendations.	Optional after content and structure exist.	Yes, always optional.
taxonomist	Category taxonomy cleanup for content-heavy existing sites.	Not part of new-site generation unless the user asks for taxonomy work.	Yes, always optional for generation.
wpcom-remote-management	Remote WordPress.com site operations via API.	Not used for local full generation; used for remote sites.	Yes for local generation.

Registered Studio tools

Tool	Purpose	When used in full generation	Can user choice skip it
create_site	Creates a local Studio site.	When the user wants a new site.	Yes, if using an existing site.
list_sites	Lists local sites.	When target site is ambiguous.	Yes, if the target is explicit.
site_info	Reads details for a target site.	When using or confirming an existing site.	Yes, if context is already enough.
start_site	Starts the local WordPress site.	Before WP CLI, screenshots, activation, or seeding if stopped.	Sometimes, if already running.
stop_site	Stops the site.	Cleanup only.	Yes.
delete_site	Deletes a local site.	Cleanup or failed experiment removal only.	Yes.
wp_cli	Runs WP CLI commands against the site.	Conditional for manual fixes, checks, or post-generation repair.	Yes, if generator and validation succeed without manual fixes.
scaffold_theme	Creates a manual theme scaffold.	Not normal full generation; useful for manual theme work.	Yes.
generate_design_previews	Generates first-fold design directions and opens them.	Normal pre-generation review step.	User can ask to skip previews, but quality is usually better with them.
generate_site	Public facade over SiteGenerationEngine. Plans, generates, validates, stages/applies.	Central tool for full generation.	No for this workflow. User can choose guided vs one-shot.
generate_image	Fills remaining theme-level AI_IMAGE placeholders.	After apply when templates/parts still need imagery.	Yes, if images are disabled, unavailable, or not needed.
validate_html_blocks	Validates block HTML.	Spot checks for generated or edited block markup.	Sometimes, if validate_and_fix_blocks covers the needed path.
validate_and_fix_blocks	Validates and repairs invalid block markup.	Normal post-generation QA.	Should not be skipped for complete generation.
take_screenshot	Captures rendered site screenshots.	Normal visual QA after apply.	Should not be skipped for complete generation.
inspect_design	Inspects rendered DOM/CSS to diagnose visual issues.	Conditional when screenshots reveal issues.	Yes, if screenshots look good.
create_preview	Creates a hosted preview site.	Optional sharing/review flow after local generation.	Yes.
list_previews	Lists preview sites.	Optional preview management.	Yes.
update_preview	Updates a preview site.	Optional preview management.	Yes.
delete_preview	Deletes a preview site.	Optional preview cleanup.	Yes.
share_screenshot	Shares screenshots in remote-session contexts.	Optional for remote review flows.	Yes.
install_taxonomy_scripts	Installs taxonomy helper scripts.	Taxonomist workflow only.	Yes for site generation.
audit_performance	Runs performance audit.	Optional final QA.	Yes.
audit_seo	Runs SEO audit.	Optional final QA.	Yes.
list_connected_remote_sites	Lists connected remote sites.	Optional sync/publish workflow.	Yes.
push_site	Pushes local site to remote.	Optional publishing/sync workflow.	Yes.
pull_site	Pulls remote site into local.	Optional sync workflow before generation or repair.	Yes.
import_site	Imports a site archive.	Optional setup path.	Yes.
export_site	Exports local site.	Optional backup/handoff path.	Yes.
open_annotation_browser	Opens annotation UI.	Optional user feedback loop.	Yes.
wait_for_annotations	Waits for annotation feedback.	Optional user feedback loop.	Yes.
studio_present	Presents rich chat artifacts when artifact emission is enabled.	Optional desktop/artifact handoff.	Yes.

Runtime tools also involved

Runtime tool	Purpose	When used	Can user choice skip it
Skill	Loads skill instructions such as site-generator and visual-design.	Normal generation routing.	No for skill-driven generation.
AskUserQuestion	Presents structured choices to the user.	Site choice, design choice, guided approval, regenerate/stop decisions.	Yes, if the prompt is explicit enough for one-shot mode.
Read, Write, Edit, Bash, Grep, Glob, Ls	Pi coding-agent file and shell tools scoped to Studio sites.	Inspection and manual repair after generated output.	Yes, if no manual repair is needed.
wpcom_request	Remote WordPress.com API tool.	Remote-site mode only.	Yes for local generation.

Internal modules behind generate_site

These live under apps/cli/ai/tools/site-generator. They are not separate user-facing tools; they are implementation modules owned by the tool layer.

Module	Responsibility
orchestrate.ts	SiteGenerationEngine phases, guided staging, one-shot apply, summaries.
manifest.ts	Manifest schema and normalization.
generators.ts	Prompt loading and model calls for theme/plugin/content artifacts.
llm.ts	Pooled non-streaming generation client, retries, cancellation/progress support.
identifier-contract.ts	Canonical block/CPT/REST identifiers and reconciliation.
build-block.ts	Custom block build compilation helpers.
images.ts	AI_IMAGE placeholder resolution in HTML.
wpcom-image.ts	Image generation proxy integration.
paths.ts	Slug derivation and path containment helpers.
seed-php.ts	Seeder PHP builder and result parser.
site-wp.ts	Site daemon and WP CLI helpers.
theme-guards.ts	Theme safety checks such as remote font and archive-loop guards.

User-choice skip points

• Existing site selected: skip site-spec detail gathering and create_site.
• User chooses "regenerate" at design review: repeat generate_design_previews, skip generation for that preview.
• User chooses "stop" at design review: no site files or DB changes.
• User asks for review before applying: use generate_site guided mode and skip apply until approval.
• User rejects guided result: keep staged artifacts but do not apply; revise spec/design and regenerate.
• User approves guided result: apply exact staged artifacts with stagedRunId; skip regeneration.
• User asks for one-shot or does not need review: skip guided staging and apply immediately.
• User disables imagery or is not logged in: skip image generation and strip/defer placeholders.
• Screenshots look good: skip inspect_design and manual repair.
• User does not need sharing, audits, remote sync, import/export, annotations, SEO, or performance checks: skip those optional tools.