From 76237aee237c7ef43c7d9a7ae3166c132c477a02 Mon Sep 17 00:00:00 2001 From: Miguel Lezama Date: Mon, 25 May 2026 08:57:55 -0300 Subject: [PATCH 1/9] Add creative-direction skill: expand vague site briefs with site-type content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a user gives a vague prompt like 'a site for a bar', Studio now loads the creative-direction skill to infer site type and expand to appropriate pages, sections, and forms (menu, events, reservations, gallery) before building — rather than defaulting to a minimal one-page placeholder. Inspired by Andrei Draganescu's Studio vs Telex comparison (May 2026): the gap was Telex's rich system-prompt assumptions for weak prompts, not design aesthetics (which Studio already covers). The fix is a skill, not a system-prompt rewrite. Changes: - apps/cli/ai/skills/creative-direction/SKILL.md: new skill with site-type detection table, per-type content plans (12 site types), design direction guidance, and instructions to brief the user before building - apps/cli/ai/system-prompt.ts: step 2 (Plan the design) now loads the creative-direction skill before writing any files Co-Authored-By: Claude Sonnet 4.6 --- .../cli/ai/skills/creative-direction/SKILL.md | 135 ++++++++++++++++++ apps/cli/ai/system-prompt.ts | 2 +- 2 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 apps/cli/ai/skills/creative-direction/SKILL.md diff --git a/apps/cli/ai/skills/creative-direction/SKILL.md b/apps/cli/ai/skills/creative-direction/SKILL.md new file mode 100644 index 0000000000..aa958dc391 --- /dev/null +++ b/apps/cli/ai/skills/creative-direction/SKILL.md @@ -0,0 +1,135 @@ +--- +name: creative-direction +description: Expand a vague site brief into a rich content and structure plan. Infer site type, choose appropriate pages and sections, make bold design decisions, and briefly tell the user what you're building — then build it without asking. +user-invokable: false +--- + +# Creative Direction + +When building a new WordPress site from a brief or vague prompt, use this skill to expand the brief into a rich content plan before writing any files. The goal: a user who types "a site for a bar" gets a site as complete and functional as one described with a detailed spec — because you make the right assumptions for them. + +## Step 1 — Detect the Site Type + +From the site name and prompt, identify the category: + +| Type | Signals | +|------|---------| +| Bar / Nightclub / Venue | bar, club, lounge, pub, tavern, speakeasy, nightlife | +| Restaurant / Café / Bakery | restaurant, café, bistro, diner, bakery, brunch, eatery | +| Coffee Shop | coffee, roastery, espresso, café + specialty/third-wave | +| Portfolio (Photo / Design / Art) | photographer, designer, artist, illustrator, studio | +| Agency / Creative Studio | agency, studio, consulting, branding, digital | +| SaaS / Tech Product | app, software, platform, tool, saas, product | +| Fitness / Gym / Yoga | gym, fitness, yoga, pilates, crossfit, wellness, studio | +| Salon / Spa / Beauty | salon, spa, beauty, barbershop, nail, aesthetics | +| Non-profit / Cause | foundation, charity, non-profit, org, cause, community | +| Real Estate | realty, properties, homes, listings, agent | +| Professional Services | law, legal, dental, medical, clinic, accounting, finance | +| Personal Blog / Magazine | blog, journal, magazine, editorial | + +## Step 2 — Expand Into Pages and Sections + +Based on the site type, decide which pages and home-page sections to create. **Do not default to a minimal one-page placeholder** when the type clearly warrants more. Below are the standard content plans — adapt based on the name and any details the user gave. + +### Bar / Nightclub / Venue +**Pages**: Home, Menu (drinks & food), Events, Gallery, Contact + Hours +**Home sections**: hero (full-bleed, mood-setting), featured events teaser, menu highlight, gallery strip, reservation CTA +**Forms**: reservation/book-a-table (Jetpack contact form), newsletter signup +**Design signal**: dark & atmospheric; bold typography; energy + +### Restaurant / Café / Bakery +**Pages**: Home, Menu, Reservations, Gallery, About, Contact +**Home sections**: hero with signature dish, menu teaser, about/story, gallery, reservation CTA +**Forms**: reservation form, contact form +**Design signal**: warm, inviting; food-photography-driven; approachable + +### Coffee Shop +**Pages**: Home, Menu, Our Story, Locations, Contact +**Home sections**: hero, signature drinks highlight, story/craft section, locations map teaser, newsletter +**Forms**: newsletter signup, contact +**Design signal**: artisanal; hand-crafted feel; warm neutrals or bold brand color + +### Portfolio (Photographer / Designer / Artist) +**Pages**: Home, Work/Portfolio (grid), About, Services, Contact +**Home sections**: full-bleed hero work, selected projects grid, brief about, services teaser, contact CTA +**Forms**: contact/inquiry form +**Design signal**: let the work breathe; minimal chrome; bold typography for name/headline + +### Agency / Creative Studio +**Pages**: Home, Services, Work/Case Studies, Team, About, Contact +**Home sections**: hero value prop, services overview, selected work, team teaser, client logos, contact CTA +**Forms**: project inquiry form, contact +**Design signal**: confident; editorial; distinctive brand identity + +### SaaS / Tech Product +**Pages**: Home (all-in-one landing), Pricing, About, Contact +**Home sections**: hero + one-line value prop, key features (3-up or 4-up), how-it-works, testimonials/social proof, pricing teaser, FAQ, final CTA +**Forms**: newsletter/waitlist signup, contact +**Design signal**: clean, modern; strong CTA hierarchy; trust signals prominent + +### Fitness / Gym / Yoga Studio +**Pages**: Home, Classes/Schedule, Memberships & Pricing, Trainers, About, Contact +**Home sections**: hero (energy/motion), classes preview, membership tiers, trainer spotlight, testimonials, CTA +**Forms**: class booking / free trial signup, contact +**Design signal**: energetic or calm (match the discipline); strong photography + +### Salon / Spa / Beauty +**Pages**: Home, Services & Pricing, Team, Gallery, Book Now, Contact +**Home sections**: hero, services overview, team highlights, gallery strip, booking CTA +**Forms**: booking/appointment form, contact +**Design signal**: luxe or friendly; clean; beauty imagery + +### Non-profit / Cause +**Pages**: Home, Mission/About, Programs, Team, Get Involved/Donate, Contact +**Home sections**: mission statement hero, impact stats, programs overview, team, call to donate/volunteer +**Forms**: donation CTA (link to external), volunteer/contact form +**Design signal**: hopeful, trustworthy, human-centered + +### Professional Services (Law / Medical / Dental / Accounting) +**Pages**: Home, Services, Team/Credentials, Testimonials, Contact +**Home sections**: hero (credibility-first), services grid, team highlight, testimonials, contact CTA +**Forms**: appointment / consultation request form +**Design signal**: authoritative, clean, trustworthy; conservative palette + +### Personal Blog / Magazine +**Pages**: Home (recent posts), About, Category archives, Contact +**Home sections**: featured post hero, recent posts grid, about blurb, newsletter +**Forms**: newsletter signup, contact +**Design signal**: editorial; typography-driven; readable + +## Step 3 — Pick a Design Direction + +Commit to a bold aesthetic that fits the site name and type. Use the name as a creative prompt: + +- *"Boogie Bar"* → dark & moody; jazz/funk energy; amber + deep black; retro-bold headlines +- *"Morning Light Bakery"* → warm, handcrafted; cream + terracotta; flowing serif display +- *"Apex Fitness"* → high-contrast; kinetic; bold sans-serif; black + electric accent +- *"Root Studio"* (yoga) → organic, grounded; earth tones; soft, breathing layout +- *"Hartley & Associates"* (law) → authoritative, minimal; navy + gold; refined serif + +The name is a creative brief. Read it. Do not default to safe/generic. + +## Step 4 — Brief the User in ≤4 Lines + +Before building, tell the user what you decided in 2–4 short lines: + +> *"Building a 5-page site for Boogie Bar: Home, Menu, Events, Gallery, and Contact. Dark & moody aesthetic with jazz-inspired typography and an amber/black palette. Includes a reservations form and a newsletter signup."* + +Then proceed immediately — **do not ask for approval**. Build it. + +## What "Rich Content" Means + +When generating page content, go beyond placeholder copy: + +- **A bar**: write actual cocktail names and descriptions, real-sounding event nights ("Jazz Thursdays", "Trivia Night"), a gallery section +- **A bakery**: name actual pastries and breads; write a "baker's story" paragraph; include seasonal specials +- **A portfolio**: write a compelling headline and 3–5 project card stubs with realistic titles +- **A SaaS**: write feature names and one-liners, realistic pricing tiers, 2–3 testimonial quotes + +Use the site name as context. Make it feel like a real site for that specific business, not a generic template. + +## When to Skip This Skill + +- User already provided detailed content (specific pages, copy, sections described) +- User explicitly said "keep it minimal", "one page", or "just a placeholder" +- Redesigning or updating an existing site diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts index 3fbad9302f..8e1be05216 100644 --- a/apps/cli/ai/system-prompt.ts +++ b/apps/cli/ai/system-prompt.ts @@ -159,7 +159,7 @@ For any request that involves a WordPress site, you MUST first determine which s Then continue with: 1. **Get site details**: Use site_info to get the site path, URL, and credentials. -2. **Plan the design**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing. +2. **Plan the design**: Before writing any code, run the \`creative-direction\` skill to expand the brief — infer site type, decide which pages and sections to create, commit to a bold design direction, and give the user a short 2–4 line summary of what you're building. Then proceed without asking for approval. Skip this if the user already provided detailed content or said to keep it minimal. 3. **Write theme/plugin files**: For a brand new theme, call \`scaffold_theme\` first — it drops an unopinionated block-theme baseline (style.css with only the theme header, theme.json with appearanceTools only, functions.php with frontend + editor style enqueue, default templates and parts, empty assets/fonts and patterns dirs) and activates it by default. Then use Write and Edit to fill the scaffold (one part/template/file per turn). For plugins or for editing an existing theme, use Write and Edit directly under the site's wp-content/themes/ or wp-content/plugins/ directory. 4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` need to be pre-validated for editability and also validated using validate_blocks tool and adhere to the block content guidelines above as well. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically. 5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again. From a1ab8c093ff4247952385fae50c03a1b6a31595d Mon Sep 17 00:00:00 2001 From: Miguel Lezama Date: Mon, 25 May 2026 11:21:18 -0300 Subject: [PATCH 2/9] Add tests for creative-direction skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 12 tests covering: - Skill discoverability (in loadSkills() output) - Body content (site-type detection, per-type content plans, design direction, brief-user instruction, skip conditions) - System prompt integration (referenced in Plan the design step, not in remote-site workflow, proceeds without asking approval) Before (trunk): creative-direction has 0 refs in system-prompt.ts and the skill directory does not exist — all integration tests would fail. After (this branch): all 12 tests pass. Co-Authored-By: Claude Sonnet 4.6 --- .../ai/tests/creative-direction-skill.test.ts | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 apps/cli/ai/tests/creative-direction-skill.test.ts diff --git a/apps/cli/ai/tests/creative-direction-skill.test.ts b/apps/cli/ai/tests/creative-direction-skill.test.ts new file mode 100644 index 0000000000..2918b65dc9 --- /dev/null +++ b/apps/cli/ai/tests/creative-direction-skill.test.ts @@ -0,0 +1,93 @@ +import { describe, expect, it } from 'vitest'; +import { buildSystemPrompt } from '../system-prompt'; +import { findSkill, loadSkills } from '../skills'; + +describe( 'creative-direction skill', () => { + describe( 'discoverability', () => { + it( 'is listed among available skills', () => { + const names = loadSkills().map( ( s ) => s.name ); + expect( names ).toContain( 'creative-direction' ); + } ); + + it( 'has a description', () => { + const skill = findSkill( 'creative-direction' ); + expect( skill?.description ).toBeTruthy(); + expect( skill?.description.length ).toBeGreaterThan( 20 ); + } ); + + it( 'is not user-invokable (internal skill)', () => { + // Creative direction is loaded by the agent automatically, not typed by users. + // Verify the frontmatter doesn't mark it as user-invokable. + const skill = findSkill( 'creative-direction' ); + // The skill body is everything after the frontmatter — user-invokable: true + // would appear in the raw file but is stripped from body by parseSkillFile. + // We test intent via the description not advertising it as a slash command. + expect( skill?.description ).not.toMatch( /slash command|type \//i ); + } ); + } ); + + describe( 'skill body content', () => { + it( 'covers site-type detection', () => { + const skill = findSkill( 'creative-direction' ); + expect( skill?.body ).toContain( 'Bar' ); + expect( skill?.body ).toContain( 'Restaurant' ); + expect( skill?.body ).toContain( 'SaaS' ); + expect( skill?.body ).toContain( 'Portfolio' ); + } ); + + it( 'includes per-type content plans with pages and forms', () => { + const skill = findSkill( 'creative-direction' ); + // Bar type should specify concrete pages and a reservations form + expect( skill?.body ).toContain( 'Menu' ); + expect( skill?.body ).toContain( 'Events' ); + expect( skill?.body ).toContain( 'Gallery' ); + expect( skill?.body ).toContain( 'reservations' ); + } ); + + it( 'instructs the agent to brief the user before building', () => { + const skill = findSkill( 'creative-direction' ); + expect( skill?.body ).toMatch( /brief the user|tell the user/i ); + expect( skill?.body ).toMatch( /do not ask for approval|proceed.*without asking/i ); + } ); + + it( 'includes a skip condition for detailed prompts', () => { + const skill = findSkill( 'creative-direction' ); + expect( skill?.body ).toMatch( /when to skip/i ); + expect( skill?.body ).toMatch( /detailed content|keep it minimal/i ); + } ); + + it( 'instructs the agent to use the site name as a design prompt', () => { + const skill = findSkill( 'creative-direction' ); + expect( skill?.body ).toMatch( /name.*creative|name.*brief|use.*name/i ); + } ); + } ); + + describe( 'system prompt integration', () => { + it( 'is referenced in the local site workflow', () => { + const prompt = buildSystemPrompt(); + expect( prompt ).toContain( 'creative-direction' ); + } ); + + it( 'is invoked during the design planning step', () => { + const prompt = buildSystemPrompt(); + // Verify the creative-direction skill reference appears in the workflow + // context (Plan the design step), not just anywhere in the prompt. + const planStep = prompt.match( /\*\*Plan the design\*\*[^\n]*/)?.[0] ?? ''; + expect( planStep ).toContain( 'creative-direction' ); + } ); + + it( 'is NOT referenced in the remote site workflow', () => { + // Remote sites use the REST API workflow — creative direction is local only. + const prompt = buildSystemPrompt( { + remoteSite: { name: 'Test Site', url: 'https://test.wordpress.com', id: 123 }, + } ); + expect( prompt ).not.toContain( 'creative-direction' ); + } ); + + it( 'instructs the agent to proceed without asking for approval', () => { + const prompt = buildSystemPrompt(); + const planStep = prompt.match( /\*\*Plan the design\*\*[^\n]*/)?.[0] ?? ''; + expect( planStep ).toContain( 'without asking for approval' ); + } ); + } ); +} ); From ff6fb3a6aedfd119f8c898903cf6a188ec4a0bae Mon Sep 17 00:00:00 2001 From: Miguel Lezama Date: Mon, 25 May 2026 12:20:11 -0300 Subject: [PATCH 3/9] Block subscriptions and other wpcom-dependent Jetpack modules in local env Add explicit caveat to the general Jetpack guidance in plugin-recommendations.ts: - List modules that require a wpcom connection (subscriptions, blaze, stats, sync) - Instruct the agent to NOT activate these in Studio's local PHP-WASM environment - Redirect newsletter signup requests to Jetpack Forms (contact-form module) Fixes the error youknowriad observed: wp jetpack module activate subscriptions Error: Newsletter could not be activated. Exit code: 1 Co-Authored-By: Claude Sonnet 4.6 --- apps/cli/ai/plugin-recommendations.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/cli/ai/plugin-recommendations.ts b/apps/cli/ai/plugin-recommendations.ts index f23570db31..c15ec2ff15 100644 --- a/apps/cli/ai/plugin-recommendations.ts +++ b/apps/cli/ai/plugin-recommendations.ts @@ -101,6 +101,7 @@ Specific Jetpack rules above (e.g. Forms) take precedence; this rule only applie wp_cli eval 'foreach (\\WP_Block_Type_Registry::get_instance()->get_all_registered() as $n => $b) if (strpos($n, "jetpack/") === 0 && (!isset($b->supports["inserter"]) || $b->supports["inserter"] !== false)) echo $n . PHP_EOL;' \`\`\` If the block you expect isn't listed, the relevant Jetpack module is probably inactive. Run \`wp_cli jetpack module list\` to see the matrix and \`wp_cli jetpack module activate \` to turn it on, then re-list. + **Important — wpcom-dependent modules**: Some modules require a WordPress.com connection and **will fail with an error** in Studio's local environment. Do NOT attempt to activate: \`subscriptions\`, \`blaze\`, \`stats\`, \`sync\`, or any module that requires a live wpcom site. For newsletter signups, use the Jetpack Forms \`contact-form\` module (already covered above) — do not activate \`subscriptions\`. 3. Use the block in the page markup and validate with \`validate_blocks\`. \`core/html\` with raw HTML stays a last resort for the cases the block content guidelines call out (inline SVG, marquee/cursor, a single bottom-of-page \`