Skip to content

CLI agent: add scaffold_theme tool#3348

Merged
youknowriad merged 4 commits into
trunkfrom
claude/focused-meitner-f10222
May 6, 2026
Merged

CLI agent: add scaffold_theme tool#3348
youknowriad merged 4 commits into
trunkfrom
claude/focused-meitner-f10222

Conversation

@youknowriad
Copy link
Copy Markdown
Contributor

@youknowriad youknowriad commented May 5, 2026 •
edited
Loading

Related issues

  • Related to AI-built sites starting from a fresh wp-content/themes/<slug>/ directory each session.

How AI was used in this PR

Iteratively designed and implemented with Claude/Codex. The final shape is intentionally narrow: provide a block-theme scaffold that removes repetitive setup work without imposing design defaults on the generated site.

Proposed Changes

Adds a scaffold_theme tool to the CLI agent so the agent does not have to regenerate the same block-theme boilerplate at the start of every site-building session.

Tool — apps/cli/ai/tools/scaffold-theme.ts

  • Args: nameOrPath, name, optional slug derived from name if omitted, optional activate defaulting to true.
  • Drops an unopinionated block-theme baseline into wp-content/themes/<slug>/:
    • style.css — WordPress theme header only.
    • theme.json — schema, version 3, and settings.appearanceTools: true only.
    • functions.php — versioned frontend style.css enqueue plus add_editor_style( 'style.css' ).
    • templates/ — index.html, single.html, page.html, archive.html, 404.html.
    • parts/ — header.html, footer.html.
    • assets/fonts/, patterns/ — empty directories.
  • Activates the theme via wp theme activate <slug> by default. If the site is not running or WP-CLI fails, the scaffold still succeeds and reports the manual activation command.
  • Refuses to clobber an existing wp-content/themes/<slug> directory.
  • Surfaces in the CLI UI as Scaffold theme (<theme name>) via the shared label/detail registry in tools/common/ai/tools.ts.

System prompt — apps/cli/ai/system-prompt.ts

  • Brand-new themes should call scaffold_theme first, then fill the scaffold with normal Write/Edit cadence.
  • The prompt describes the scaffold as unopinionated so the model still owns visual direction, palette, typography, and layout quality.
  • The style.css cadence rule tells the agent to append tokens and section anchors below the scaffolded theme header instead of overwriting it.
  • The verification workflow still requires checking HTML block misuse, block validation, and desktop/mobile screenshots.

Tests — apps/cli/ai/tests/tools.test.ts

Real-fs scaffolding into a temp directory; covers tool registration, full file creation, explicit slug override, activate: false, default activation when site is running, activation skipped when site is not running, activation skipped on WP-CLI non-zero exit, theme-already-exists guard, missing wp-content/themes guard, invalid slug, and empty name.

Testing Instructions

  1. npm install then npm run cli:build.
  2. Start a Studio site or use an existing running site.
  3. Spawn the CLI agent against that site and ask it to build a custom theme. The first turn after onboarding should be a scaffold_theme call rendered as Scaffold theme (<name>) in the CLI UI.
  4. Verify in the WP admin that the new theme is active and that style.css, theme.json, functions.php, all five templates, and both parts are present under wp-content/themes/<slug>/.
  5. From the worktree, run:
    • ./node_modules/.bin/eslint --fix apps/cli/ai/system-prompt.ts apps/cli/ai/tools/scaffold-theme.ts apps/cli/ai/tests/tools.test.ts
    • npm run typecheck
    • npm test -- apps/cli/ai/tests/tools.test.ts
    • npm run cli:build

Pre-merge Checklist

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

🤖 Generated with Codex

@youknowriad @claude
CLI agent: add scaffold_theme tool
14b7733 
Adds a scaffold_theme tool that drops a minimal block-theme baseline
(style.css with WP header + UX fixes, theme.json with appearanceTools,
useRootPaddingAwareAlignments and a sane palette/spacing/typography scale,
functions.php that enqueues style.css on the frontend and as editor styles,
default templates and parts, empty assets/fonts and patterns dirs) and
activates the theme by default. When the site is not running or activation
fails, the scaffold still succeeds and the result reports the manual
activation command.

Templates use a plain <main> wrapper with an inner constrained group
(or constrained wp:post-content for page/single) so align:"full" sections
in user content reliably reach viewport width.

System-prompt updates: scaffold_theme appears in the available tools list,
the theme-build workflow recommends calling it first, the
"never scaffold a whole theme" rule carves out the scaffold call, the
duplicated frontend/editor enqueue rules collapse into one general rule,
and the style.css skeleton-first guidance now branches to Edit (not Write)
when the scaffolded file is already on disk. Tool label and detail also
registered in the shared tools.ts registry so the CLI UI shows
"Scaffold theme (<name>)".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@wpmobilebot
Copy link
Copy Markdown
Collaborator

wpmobilebot commented May 5, 2026 •
edited
Loading

📊 Performance Test Results

Comparing a59ced6 vs trunk

app-size

Metric trunk a59ced6 Diff Change
App Size (Mac) 1404.87 MB 1454.06 MB +49.20 MB 🔴 3.5%

site-editor

Metric trunk a59ced6 Diff Change
load 1505 ms 1506 ms +1 ms ⚪ 0.0%

site-startup

Metric trunk a59ced6 Diff Change
siteCreation 8093 ms 8086 ms 7 ms ⚪ 0.0%
siteStartup 4939 ms 4951 ms +12 ms ⚪ 0.0%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

youknowriad and others added 3 commits May 5, 2026 22:22
@youknowriad @claude
scaffold_theme: ship front-page.html and route homepages to it
9a2054d 
Adds a minimal front-page.html to the scaffold (header part, plain <main>,
unconstrained wp:post-content, footer part) so one-page builds have a
purpose-built home canvas with no constrained-layout interference.

System prompt updates:
- Step 3 now points homepage layouts at templates/front-page.html and
  reserves templates/page.html for interior pages.
- The "Page content" cadence rule splits into a Homepage bullet (Edit
  front-page.html directly, replace the post-content reference with
  section anchors, fill via Edits) and an Interior-page bullet (existing
  empty-page + tmp file + wp_cli eval workflow). Skipping the DB-page
  round trip for the homepage saves several turns per session.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@youknowriad @claude
scaffold_theme: richer output, consolidate homepage rule into step 3
76f9e33 
scaffold_theme tool result now includes:
- the absolute theme directory at the top so the agent doesn't need a
  follow-up site_info call to construct Edit file_paths;
- a one-line content description per file (style.css, theme.json,
  functions.php, every template, both parts) so the agent can plan
  targeted Edits without Reading first.

System prompt: the Homepage workflow rule was buried under "Long files:
skeleton first" — a section about file *length*, which doesn't cue the
agent on homepage authoring. Move that guidance into step 3 of the build
workflow (right after the scaffold_theme call) so the agent sees the
front-page.html path before reaching the wp_cli "configure WordPress"
step. The Homepage bullet under "Long files" is removed; the
interior-page bullet stays put.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@youknowriad
Simplify scaffold theme defaults
a59ced6
@youknowriad youknowriad merged commit 9b3fe92 into trunk May 6, 2026
11 checks passed
@youknowriad youknowriad deleted the claude/focused-meitner-f10222 branch May 6, 2026 12:41
@youknowriad
Copy link
Copy Markdown
Contributor Author

youknowriad commented May 6, 2026

This is producing more complete themes and sites.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@youknowriad youknowriad

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@youknowriad @wpmobilebot