Skip to content

Add creative-direction skill for vague site briefs - #3629

Draft
lezama wants to merge 1 commit into
trunkfrom
creative-direction-v2
Draft

Add creative-direction skill for vague site briefs#3629
lezama wants to merge 1 commit into
trunkfrom
creative-direction-v2

Conversation

@lezama

@lezama lezama commented May 27, 2026

Copy link
Copy Markdown
Contributor

What

Adds a creative-direction skill that expands a vague site brief into a rich content and structure plan — choosing pages, sections, hero framing, and copy direction — before the agent starts building.

Follows the skill-routing pattern established in #3605.

Why

When a user says "make a site for my bar", the agent has to guess what pages, sections, and tone to use. Without a planning step it either under-builds (minimal skeleton) or over-asks (wizard-like back-and-forth). This skill lets the agent commit to a concrete creative direction and then build confidently, with no user interruption.

Changes

  • apps/cli/ai/skills/creative-direction/SKILL.md — the skill: site-type inference, page/section inventory, hero framing, copy direction, confidence rules
  • apps/cli/ai/system-prompt.ts — two small routing lines:
    • Invocation trigger in the global skill-routing block (For new sites built from a vague brief…)
    • Reference in the "Plan the design" step of the site-building workflow
  • apps/cli/ai/tests/creative-direction-skill.test.ts — 14 unit tests covering invocation conditions, confidence rules, and system prompt integration (all pass)

What changed vs the earlier draft (#3610)

#3610 predated #3605 and made large edits to system-prompt.ts (+152 / −0 lines) plus touched several other files. This PR is a clean rebase:

Testing

npm run cli:build

Then in Studio AI chat: "crea un sitio para una hamburguesería" — agent should load creative-direction, plan pages/sections, then start building without asking for approval.

Rebuilt on top of #3605's skill-routing architecture:

- Skill lives in apps/cli/ai/skills/creative-direction/SKILL.md
- System prompt only adds: (a) routing pointer in LOCAL_SKILL_ROUTING,
  (b) one-sentence reference in the local 'Plan the design' step.
- Skill itself contains all the expansion logic (Step 0 gauge, type
  detection, page/section recipes, design-direction commitments).
- Skill is invoked only when the agent decides the brief is vague —
  not on every site creation. Validation built into Step 0 via the
  three explicit modes: auto-expand, ask one question, or skip.

Tests: apps/cli/ai/tests/creative-direction-skill.test.ts (14 pass).
@wpmobilebot

Copy link
Copy Markdown
Collaborator

📊 Performance Test Results

Comparing 66bee27 vs trunk

app-size

Metric trunk 66bee27 Diff Change
App Size (Mac) 1335.92 MB 1335.92 MB +0.00 MB ⚪ 0.0%

site-editor

Metric trunk 66bee27 Diff Change
load 1743 ms 1755 ms +12 ms ⚪ 0.0%

site-startup

Metric trunk 66bee27 Diff Change
siteCreation 9603 ms 9608 ms +5 ms ⚪ 0.0%
siteStartup 4929 ms 4916 ms 13 ms ⚪ 0.0%

Results are median values from multiple test runs.

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

@lezama
lezama marked this pull request as draft May 27, 2026 20:28
@lezama

lezama commented May 27, 2026

Copy link
Copy Markdown
Contributor Author

Picking up @youknowriad's question from #3610 — marking this as a PoC so the team has something concrete to evaluate.

This PR implements approach 2 (auto-expansion, like Telex). Here's how the three approaches play out in practice:

  1. No expansion (trunk today): Agent gets "make a site for my bar" and has to guess everything — usually produces a minimal skeleton.
  2. Auto-expansion (this PR / Telex): Agent infers site type, commits to pages/sections/aesthetic, briefs the user in 2–3 lines, then builds. No user interruption. This is also what Telex does: it generates a structured site spec (layoutMode, heroComposition, typography) before writing a single file.
  3. Guided expansion (BigSky wizard): Agent asks targeted questions before building. More control for the user, more friction in the flow.

The Telex observation is relevant here: Telex's better output quality comes specifically from committing to a heroComposition (cinematic prose describing the spatial composition) and inferring typography from site type — both happen before any file is written, without asking the user. That's approach 2.

On Riad's concern about merging with site-spec: agreed — a separate skill for the same purpose is redundant. A follow-up PR will fold this into site-spec so there's one skill that handles both name/layout gathering and creative direction expansion when the brief is vague.

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

2 participants