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
Copy link
Copy Markdown
Contributor

@lezama lezama commented May 27, 2026

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
Copy link
Copy Markdown
Contributor Author

lezama commented May 27, 2026

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants