From 11343d76fc2f55ab9d1c1db6dd555094eaec38e8 Mon Sep 17 00:00:00 2001 From: Miguel Lezama Date: Wed, 27 May 2026 17:30:49 -0300 Subject: [PATCH] site-spec: expand into creative direction (layout, hero composition, typography) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Instead of asking 'one-page or multi-page?', the skill now auto-infers layout, pages/sections, hero composition, and typography from the site name — then briefs the user in ≤4 lines before building. Inspired by Telex's approach: committing to a heroComposition (cinematic prose describing spatial composition) and inferring typography from site type are the two changes that most improve output quality. Folds the separate creative-direction skill into site-spec as Riad suggested — one skill for gathering user needs and expanding the brief. Co-Authored-By: Claude Sonnet 4.6 --- apps/cli/ai/skills/site-spec/SKILL.md | 57 +++++++++++++++++++-------- apps/cli/ai/system-prompt.ts | 2 +- 2 files changed, 42 insertions(+), 17 deletions(-) diff --git a/apps/cli/ai/skills/site-spec/SKILL.md b/apps/cli/ai/skills/site-spec/SKILL.md index e04b9c73ef..5c014c1954 100644 --- a/apps/cli/ai/skills/site-spec/SKILL.md +++ b/apps/cli/ai/skills/site-spec/SKILL.md @@ -1,39 +1,64 @@ --- name: site-spec -description: Gather the site name and layout preference before building a WordPress site. Run this before creating any new site. +description: Gather the site name, then auto-expand into a creative direction (pages, layout, hero, typography) before building a WordPress site. Run this before creating any new site. user-invokable: true --- # Site Spec Discovery -Before creating a new WordPress site, gather the user's basic preferences through a short interactive discovery phase. This produces a **Site Spec** that guides all subsequent design and development decisions. +Before creating a new WordPress site, gather the user's name and expand it into a full creative direction. This produces a **Site Spec** that guides all subsequent design and development decisions. -## How to Run +**AskUserQuestion constraints**: Each call supports 1-4 questions, each with 2-4 options. An "Other" free-form option is automatically provided by the system — do NOT add one yourself. Keep option labels short (1-5 words). Only use AskUserQuestion for questions that have meaningful predefined options. For open-ended questions (like asking for a name), just ask in your text output — the user will type their answer in the prompt. -Gather preferences through 2 rounds. Keep it concise. +## Round 1 — Name -**AskUserQuestion constraints**: Each call supports 1-4 questions, each with 2-4 options. An "Other" free-form option is automatically provided by the system — do NOT add one yourself. Keep option labels short (1-5 words). Only use AskUserQuestion for questions that have meaningful predefined options. For open-ended questions (like asking for a name), just ask in your text output — the user will type their answer in the prompt. +Ask the user for their business/site name in your text output — unless it was already stated clearly in their message (e.g. *"create a site called Pan de Casa"*), in which case use it directly and skip to Round 2. + +**Critical**: if you ask the name question, your response must end immediately after that question. No tool calls. No Round 2. No extra text. The user will type their answer and send it — only after receiving their reply do you move to Round 2. + +## Round 2 — Expand into a Creative Direction + +Once you have the name, **do not ask questions about layout or pages**. Instead, infer everything from the name and context, commit to a concrete creative direction, and brief the user before building. + +### Step A — Read the brief + +| Signal | Action | +|--------|--------| +| Site type is clear ("Bar Boogie", "Morning Light Bakery") | Auto-expand — go to Step B | +| Site type is ambiguous ("a site for my business") | Ask **one** specific question to resolve it, then go to Step B | +| User said "minimal", "one page", or "just a placeholder" | Skip expansion — use a simple one-page layout, go to Step C | + +### Step B — Decide the four pillars + +Commit to all of these without asking: + +**Layout** — Pick the shape that fits the site type: +- `vertical-stack` — standard header/content/footer (default) +- `landing-page` — single scrollable page, anchor-linked sections (portfolios, product launches, one-pager requests) +- `magazine-grid` — homepage is a post archive (blogs, publications) +- `canvas` — full-bleed imagery, floating chrome (photography, art portfolios) + +**Pages & sections** — Decide which pages to create and what sections go on each. A bar needs Home + Menu + Events + Contact; a SaaS needs Home (features/pricing/CTA) + About + Contact. Match the type — don't default to a minimal skeleton. -### Round 1 — Name +**Hero composition** — One short paragraph of cinematic prose: composition strategy (full-bleed / asymmetric / centered / split), image placement, typographic weight, overall mood. This is the spatial anchor that guides downstream block choices. Example: *"A full-bleed photo of latte art fills the right two-thirds of the screen. Display-serif type sits left, large and slightly oversized. A single rust-colored CTA rests low with generous breathing room. The composition feels still, like a held breath."* -Ask the user for their business/site name in your text output. **Stop here and wait for their reply** — do NOT call any tools or continue to the next round. The user needs a chance to type their answer in the prompt. +**Typography** — A font pairing that fits the name and type. Examples: coffee shop → Fraunces + Spectral; law firm → Cormorant Garamond + Source Sans; esports → Rajdhani + JetBrains Mono. When the signal is weak, default to a clean humanist pair. -### Round 2 — Layout +### Step C — Brief the user in ≤4 lines -After the user provides the name, use AskUserQuestion for: -- One-page site or multi-page site? (e.g., single scrollable page with sections vs. separate pages for each area) +Tell the user what you decided before building. Example: -## After Gathering Answers +> *"Building a 5-page site for Boogie Bar: Home, Menu, Events, Gallery, and Contact. Dark & moody aesthetic, jazz-inspired typography, amber/black palette. Includes a reservations form and newsletter signup."* -Call `site_create` with the provided name and use the layout preference to guide all subsequent design decisions. +**Do not ask for approval.** Proceed immediately to `site_create`. ## After site_create returns -The turn immediately after `site_create` is the biggest source of perceived hangs. Acknowledge the site in ≤2 lines of prose, then make your next tool call a small one — `site_info`, or a single ≤50-line first `Write`. Do NOT scaffold the theme, chain multiple Writes, or write a long design-plan essay in this turn. Grow the build across many small turns (see the "Working cadence" section of the system prompt). +The turn immediately after `site_create` is the biggest source of perceived hangs. Acknowledge the site in ≤2 lines of prose, then make your next tool call a small one — `site_info`, or a single ≤50-line first `Write`. Do NOT scaffold the theme, chain multiple Writes, or write a long design-plan essay in this turn. Grow the build across many small turns. ## When to Skip Discovery -Do NOT ask questions if: -- The user already provided the name and layout preference in the initial prompt. Proceed directly with site creation. +Do NOT run this skill if: +- The user already provided the name AND a detailed layout/content spec. Proceed directly with site creation. - The user says "just build something" or "surprise me". Pick a bold creative direction yourself and proceed. -- The user explicitly asks to skip the setup or says they don't want questions. +- The user explicitly asks to skip setup. diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts index ff3b099c06..fdbff41e6b 100644 --- a/apps/cli/ai/system-prompt.ts +++ b/apps/cli/ai/system-prompt.ts @@ -107,7 +107,7 @@ For any request that involves a WordPress site, you MUST first determine which s - **Active site + ambiguous "create" / "build" / "make" / "design a site"**: Ask whether to update the active site or create a separate new site before calling site_create. Use AskUserQuestion when available with options like "Use current site" and "Create new site". - **Active site + explicit "new" / "separate" / "another" site**: Run the \`site-spec\` skill to gather the site name and layout preference FIRST, then call site_create. -- **No active site + "create" / "build" / "make" a site**: Run the \`site-spec\` skill to gather the site name and layout preference FIRST, then call site_create. +- **No active site + "create" / "build" / "make" a site**: Run the \`site-spec\` skill FIRST — it gathers the site name and expands the brief into a creative direction (pages, layout, hero, typography), then call site_create. - **"Redesign" / "update" / "change this site"**: Reuse the active site. - **User names a specific existing site**: Call site_list to find it. - **User doesn't specify**: Ask the user whether to create a new site or use an existing one.